knowns 0.8.1 → 0.8.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +3 -2
- package/dist/index.js +94 -26
- package/dist/mcp/server.js +59 -1
- package/dist/ui/assets/{index-CgrPuyyK.js → index-D3_NArD-.js} +1 -1
- package/dist/ui/index.html +1 -1
- package/package.json +1 -2
- package/CLAUDE.md +0 -999
package/README.md
CHANGED
|
@@ -121,8 +121,9 @@ knowns time start <id> && knowns time stop
|
|
|
121
121
|
knowns search "query" --plain
|
|
122
122
|
|
|
123
123
|
# AI Guidelines
|
|
124
|
-
knowns agents
|
|
125
|
-
knowns agents sync
|
|
124
|
+
knowns agents guideline # Output guidelines to stdout
|
|
125
|
+
knowns agents sync # Sync CLAUDE.md, AGENTS.md (minimal)
|
|
126
|
+
knowns agents sync --full # Sync with full embedded guidelines
|
|
126
127
|
knowns agents sync --type mcp # MCP tools format
|
|
127
128
|
```
|
|
128
129
|
|
package/dist/index.js
CHANGED
|
@@ -43475,17 +43475,20 @@ import { mkdir as mkdir3, readFile as readFile2, writeFile as writeFile2 } from
|
|
|
43475
43475
|
import { dirname, join as join3 } from "node:path";
|
|
43476
43476
|
var import_prompts = __toESM(require_prompts3(), 1);
|
|
43477
43477
|
|
|
43478
|
-
// src/templates/cli/gemini.md
|
|
43479
|
-
var gemini_default = '<!-- KNOWNS GUIDELINES START -->\n# Knowns CLI - Gemini Quick Reference\n\n## RULES\n- NEVER edit .md files directly - use CLI only\n- Use `--plain` flag for VIEW/LIST/SEARCH commands only (NOT for create/edit)\n- Read docs BEFORE coding\n- Start timer when taking task, stop when done\n\n## SESSION START\n```bash\nknowns doc list --plain\nknowns doc "README" --plain\nknowns task list --plain\n```\n\n## TASK WORKFLOW\n\n### 1. Take Task\n```bash\nknowns task <id> --plain # View task\nknowns task edit <id> -s in-progress -a @me\nknowns time start <id>\n```\n\n### 2. Read Context\n```bash\nknowns doc list "guides/" --plain # List by folder\nknowns doc "path/name" --plain # View doc\nknowns search "keyword" --type doc --plain\n```\n\n### 3. Plan & Implement\n```bash\nknowns task edit <id> --plan $\'1. Step one\\n2. Step two\'\n# Wait for approval, then code\nknowns task edit <id> --check-ac 1 # Check criteria after done\nknowns task edit <id> --append-notes "Done: feature X"\n```\n\n### 4. Complete\n```bash\nknowns time stop\nknowns task edit <id> -s done\n```\n\n## COMMANDS CHEATSHEET\n\n### Task\n```bash\nknowns task list --plain\nknowns task list --status in-progress --plain\nknowns task <id> --plain\nknowns task create "Title" -d "Desc" --ac "Criterion" --priority high\nknowns task edit <id> -s <status> -a @me\nknowns task edit <id> --check-ac 1 --check-ac 2\nknowns task edit <id> --plan "..."\nknowns task edit <id> --notes "..."\nknowns task edit <id> --append-notes "..."\n```\n\n### Doc\n```bash\nknowns doc list --plain\nknowns doc list "folder/" --plain\nknowns doc "name" --plain\nknowns doc create "Title" -d "Desc" -t "tags" -f "folder"\nknowns doc edit "name" -c "content"\nknowns doc edit "name" -a "append"\nknowns doc edit "name" --content-file ./file.md\nknowns doc edit "name" --append-file ./file.md\nknowns doc search-in "name" "query" --plain\nknowns doc replace "name" "old" "new"\n```\n\n**Doc Organization:**\n| Type | Location |\n|------|----------|\n| Core docs | Root `.knowns/docs/` (no -f flag) |\n| Categorized | `.knowns/docs/<folder>/` (use -f flag) |\n\n### Time\n```bash\nknowns time start <id>\nknowns time stop\nknowns time status\nknowns time add <id> 2h -n "Note"\n```\n\n### Search\n```bash\nknowns search "query" --plain\nknowns search "query" --type doc --plain\nknowns search "query" --type task --plain\n```\n\n## REFS\n\n### Reading (output format)\n- `@.knowns/tasks/task-X - Title.md` \u2192 `knowns task X --plain`\n- `@.knowns/docs/path/name.md` \u2192 `knowns doc "path/name" --plain`\n\n### Writing (input format)\n- Task: `@task-X`\n- Doc: `@doc/path/name`\n\n## STATUS & PRIORITY\n\n**Status:** `todo`, `in-progress`, `in-review`, `blocked`, `done`\n**Priority:** `low`, `medium`, `high`\n\n## --plain FLAG\n\n\u26A0\uFE0F **CRITICAL**: Only use `--plain` with VIEW/LIST/SEARCH commands!\n\n| \u2705 Supports --plain | \u274C NO --plain |\n|---------------------|---------------|\n| `task <id> --plain` | `task create` |\n| `task list --plain` | `task edit` |\n| `doc <path> --plain` | `doc create` |\n| `doc list --plain` | `doc edit` |\n| `search --plain` | `time start/stop/add` |\n\n## LONG CONTENT\n\nWindows has ~8191 char limit. Use:\n\n```bash\n# Append in chunks\nknowns doc edit "name" -a "Section 1..."\nknowns doc edit "name" -a "Section 2..."\n\n# Or file-based\nknowns doc edit "name" --content-file ./content.md\nknowns doc edit "name" --append-file ./more.md\n```\n\n## VALIDATE & REPAIR\n\n```bash\nknowns doc validate "name" --plain\nknowns doc repair "name" --plain\nknowns task validate <id> --plain\nknowns task repair <id> --plain\n```\n<!-- KNOWNS GUIDELINES END -->\n';
|
|
43480
|
-
|
|
43481
43478
|
// src/templates/cli/general.md
|
|
43482
|
-
var general_default = '<!-- KNOWNS GUIDELINES START -->\n# Knowns CLI Guidelines\n\n## Core Principles\n\n### 1. CLI-Only Operations\n**NEVER edit .md files directly. ALL operations MUST use CLI commands.**\n\nThis ensures data integrity, maintains proper change history, and prevents file corruption.\n\n### 2. Documentation-First (For AI Agents)\n**ALWAYS read project documentation BEFORE planning or coding.**\n\nAI agents must understand project context, conventions, and existing patterns before making any changes. This prevents rework and ensures consistency.\n\n---\n\n## AI Agent Guidelines\n\n> **CRITICAL**: Before performing ANY task, AI agents MUST read documentation to understand project context.\n\n### First-Time Initialization\n\nWhen starting a new session or working on an unfamiliar project:\n\n```bash\n# 1. List all available documentation\nknowns doc list --plain\n\n# 2. Read essential project docs (prioritize these)\nknowns doc "README" --plain # Project overview\nknowns doc "ARCHITECTURE" --plain # System design\nknowns doc "CONVENTIONS" --plain # Coding standards\nknowns doc "API" --plain # API specifications\n\n# 3. Review current task backlog\nknowns task list --plain\nknowns task list --status in-progress --plain\n```\n\n### Before Taking Any Task\n\n```bash\n# 1. View the task details\nknowns task <id> --plain\n\n# 2. Follow ALL refs in the task (see Reference System section)\n# @.knowns/tasks/task-44 - ... \u2192 knowns task 44 --plain\n# @.knowns/docs/patterns/module.md \u2192 knowns doc "patterns/module" --plain\n\n# 3. Search for additional related documentation\nknowns search "<keywords from task>" --type doc --plain\n\n# 4. Read ALL related docs before planning\nknowns doc "<related-doc>" --plain\n\n# 5. Check for similar completed tasks (learn from history)\nknowns search "<keywords>" --type task --status done --plain\n```\n\n### Why Documentation First?\n\n| Without Reading Docs | With Reading Docs |\n|---------------------|-------------------|\n| Reinvent existing patterns | Reuse established patterns |\n| Break conventions | Follow project standards |\n| Duplicate code | Use existing utilities |\n| Wrong architecture decisions | Align with system design |\n| Inconsistent naming | Match naming conventions |\n\n### Context Checklist for Agents\n\nBefore writing ANY code, ensure you can answer:\n\n- [ ] Have I followed ALL refs (`@.knowns/...`) in the task?\n- [ ] Have I followed nested refs recursively?\n- [ ] What is the project\'s overall architecture?\n- [ ] What coding conventions does this project follow?\n- [ ] Are there existing patterns/utilities I should reuse?\n- [ ] What are the testing requirements?\n- [ ] How should I structure my implementation?\n\n> **Remember**: A few minutes reading docs saves hours of rework. NEVER skip this step.\n\n---\n\n## Reference System (Refs)\n\nTasks and docs can contain **references** to other tasks/docs. AI agents MUST understand and follow these refs to gather complete context.\n\n### Reference Formats\n\n| Type | When Writing (Input) | When Reading (Output) | CLI Command |\n|------|---------------------|----------------------|-------------|\n| **Task ref** | `@task-<id>` | `@.knowns/tasks/task-<id> - <title>.md` | `knowns task <id> --plain` |\n| **Doc ref** | `@doc/<path>` | `@.knowns/docs/<path>.md` | `knowns doc <path> --plain` |\n\n> **CRITICAL for AI Agents**:\n> - When **WRITING** refs (in descriptions, plans, notes): Use `@task-<id>` and `@doc/<path>`\n> - When **READING** output from `--plain`: You\'ll see `@.knowns/tasks/...` and `@.knowns/docs/...`\n> - **NEVER write** the output format (`@.knowns/...`) - always use input format (`@task-<id>`, `@doc/<path>`)\n\n### How to Follow Refs\n\nWhen you read a task and see refs in system output format, follow them:\n\n```bash\n# Example: Task 42 output contains:\n# @.knowns/tasks/task-44 - CLI Task Create Command.md\n# @.knowns/docs/patterns/module.md\n\n# Follow task ref (extract ID from task-<id>)\nknowns task 44 --plain\n\n# Follow doc ref (extract path, remove .md)\nknowns doc "patterns/module" --plain\n```\n\n### Parsing Rules\n\n1. **Task refs**: `@.knowns/tasks/task-<id> - ...` \u2192 extract `<id>` \u2192 `knowns task <id> --plain`\n2. **Doc refs**: `@.knowns/docs/<path>.md` \u2192 extract `<path>` \u2192 `knowns doc "<path>" --plain`\n\n### Recursive Following\n\nRefs can be nested. Follow until complete context is gathered:\n\n```\nTask 42\n \u2192 @.knowns/docs/README.md\n \u2192 @.knowns/docs/patterns/module.md (found in README)\n \u2192 (read for full pattern details)\n```\n\n### When to Follow Refs\n\n| Situation | Action |\n|-----------|--------|\n| Refs in Description | ALWAYS follow - critical context |\n| Refs in Implementation Plan | Follow if implementing related work |\n| Refs in Notes | Optional - for historical context |\n| Dependency mentions | Follow if marked as blocker |\n\n### Example: Complete Ref Resolution\n\n```bash\n# 1. Read the task\n$ knowns task 42 --plain\n\n# Output contains:\n# @.knowns/tasks/task-44 - CLI Task Create Command.md\n# @.knowns/docs/README.md\n\n# 2. Follow task ref\n$ knowns task 44 --plain\n\n# 3. Follow doc ref\n$ knowns doc "README" --plain\n\n# 4. If README contains more refs, follow them too\n# @.knowns/docs/patterns/module.md \u2192 knowns doc "patterns/module" --plain\n\n# Now you have complete context\n```\n\n> **CRITICAL**: Never assume you understand a task fully without following its refs. Refs contain essential context that may change your implementation approach.\n\n---\n\n## Quick Start\n\n```bash\n# Initialize project\nknowns init [name]\n\n# Create task with acceptance criteria\nknowns task create "Title" -d "Description" --ac "Criterion 1" --ac "Criterion 2"\n\n# View task (ALWAYS use --plain for AI)\nknowns task <id> --plain # Shorthand\nknowns task view <id> --plain # Full command\n\n# View doc (ALWAYS use --plain for AI)\nknowns doc <path> --plain # Shorthand\nknowns doc view "<path>" --plain # Full command\n\n# List tasks\nknowns task list --plain\n\n# Search (tasks + docs)\nknowns search "query" --plain\n```\n\n---\n\n## End-to-End Example\n\nHere\'s a complete workflow for an AI agent implementing a feature:\n\n```bash\n# === AGENT SESSION START (Do this once per session) ===\n\n# 0a. List all available documentation\n$ knowns doc list --plain\n\n# Output:\n# DOC: README.md\n# DOC: ARCHITECTURE.md\n# DOC: CONVENTIONS.md\n# DOC: security-patterns.md\n# DOC: api-guidelines.md\n# DOC: email-templates.md\n\n# 0b. Read essential project docs\n$ knowns doc "README" --plain\n$ knowns doc "ARCHITECTURE" --plain\n$ knowns doc "CONVENTIONS" --plain\n\n# Now the agent understands project context and conventions\n\n# === TASK WORKFLOW ===\n\n# 1. Create the task\n$ knowns task create "Add password reset flow" \\\n -d "Users need ability to reset forgotten passwords via email" \\\n --ac "User can request password reset via email" \\\n --ac "Reset link expires after 1 hour" \\\n --ac "User can set new password via reset link" \\\n --ac "Unit tests cover all scenarios" \\\n --priority high \\\n -l "auth,feature"\n\n# Output: Created task AUTH-042\n\n# 2. Take the task and start timer (uses defaultAssignee or @me fallback)\n$ knowns task edit AUTH-042 -s in-progress -a $(knowns config get defaultAssignee --plain || echo "@me")\n$ knowns time start AUTH-042\n\n# Output: Timer started for AUTH-042\n\n# 3. Search for related documentation\n$ knowns search "password security" --type doc --plain\n\n# Output:\n# DOC: security-patterns.md (score: 0.92)\n# DOC: email-templates.md (score: 0.78)\n\n# 4. Read the documentation\n$ knowns doc "security-patterns" --plain\n\n# 5. Create implementation plan (SHARE WITH USER, WAIT FOR APPROVAL)\n$ knowns task edit AUTH-042 --plan $\'1. Review security patterns (see @doc/security-patterns)\n2. Design token generation with 1-hour expiry\n3. Create email template (see @doc/email-templates)\n4. Implement /forgot-password endpoint\n5. Implement /reset-password endpoint\n6. Add unit tests\n7. Update API documentation\'\n\n# 6. After approval, implement and check criteria as you go\n$ knowns task edit AUTH-042 --check-ac 1\n$ knowns task edit AUTH-042 --append-notes "\u2713 Implemented /forgot-password endpoint"\n\n$ knowns task edit AUTH-042 --check-ac 2\n$ knowns task edit AUTH-042 --append-notes "\u2713 Token expiry set to 1 hour"\n\n$ knowns task edit AUTH-042 --check-ac 3\n$ knowns task edit AUTH-042 --append-notes "\u2713 Implemented /reset-password endpoint"\n\n$ knowns task edit AUTH-042 --check-ac 4\n$ knowns task edit AUTH-042 --append-notes "\u2713 Added 12 unit tests, 100% coverage"\n\n# 7. Add final implementation notes\n$ knowns task edit AUTH-042 --notes $\'## Summary\nImplemented complete password reset flow with secure token generation.\n\n## Changes\n- Added POST /forgot-password endpoint\n- Added POST /reset-password endpoint\n- Created password_reset_tokens table\n- Added email template for reset link\n\n## Security\n- Tokens use crypto.randomBytes(32)\n- 1-hour expiry enforced at DB level\n- Rate limiting: 3 requests per hour per email\n\n## Tests\n- 12 unit tests added\n- Coverage: 100% for new code\n\n## Documentation\n- Updated API.md with new endpoints\'\n\n# 8. Stop timer and complete\n$ knowns time stop\n$ knowns task edit AUTH-042 -s done\n\n# Output: Task AUTH-042 marked as done\n```\n\n---\n\n## Task Workflow\n\n### Step 1: Take Task\n\n```bash\n# Assign using defaultAssignee from config (falls back to @me if not set)\nknowns task edit <id> -s in-progress -a $(knowns config get defaultAssignee --plain || echo "@me")\n```\n\n> **Note**: The `defaultAssignee` is configured in `.knowns/config.json` during `knowns init`. If not set, `@me` is used as fallback. To update: `knowns config set defaultAssignee "@username"`\n\n### Step 2: Start Time Tracking (REQUIRED)\n\n```bash\nknowns time start <id>\n```\n\n> **CRITICAL**: Time tracking is MANDATORY. Always start timer when taking a task and stop when done. This data is essential for:\n> - Accurate project estimation\n> - Identifying bottlenecks\n> - Resource planning\n> - Sprint retrospectives\n\n### Step 3: Read Related Documentation\n\n> **FOR AI AGENTS**: This step is MANDATORY, not optional. You must understand the codebase before planning.\n\n```bash\n# Search for related docs\nknowns search "authentication" --type doc --plain\n\n# View relevant documents\nknowns doc "API Guidelines" --plain\nknowns doc "Security Patterns" --plain\n\n# Also check for similar completed tasks\nknowns search "auth" --type task --status done --plain\n```\n\n> **CRITICAL**: ALWAYS read related documentation BEFORE planning! Understanding existing patterns and conventions prevents rework and ensures consistency.\n\n### Step 4: Create Implementation Plan\n\n```bash\nknowns task edit <id> --plan $\'1. Research patterns (see @doc/security-patterns)\n2. Design middleware\n3. Implement\n4. Add tests\n5. Update docs\'\n```\n\n> **CRITICAL**:\n> - Share plan with user and **WAIT for approval** before coding\n> - Include doc references using `@doc/<path>` format\n\n### Step 5: Implement\n\n```bash\n# Work through implementation plan step by step\n# IMPORTANT: Only check AC AFTER completing the work, not before\n\n# After completing work for AC #1:\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "\u2713 Completed: <brief description>"\n\n# After completing work for AC #2:\nknowns task edit <id> --check-ac 2\nknowns task edit <id> --append-notes "\u2713 Completed: <brief description>"\n```\n\n> **CRITICAL**: Never check an AC before the work is actually done. ACs represent completed outcomes, not intentions.\n\n### Step 6: Handle Dynamic Requests (During Implementation)\n\nIf the user adds new requirements during implementation:\n\n```bash\n# Add new acceptance criteria\nknowns task edit <id> --ac "New requirement from user"\n\n# Update implementation plan to include new steps\nknowns task edit <id> --plan $\'1. Original step 1\n2. Original step 2\n3. NEW: Handle user request for X\n4. Continue with remaining work\'\n\n# Append note about scope change\nknowns task edit <id> --append-notes "\u26A0\uFE0F Scope updated: Added requirement for X per user request"\n\n# Continue with Step 5 (Implement) for new requirements\n```\n\n> **Note**: Always document scope changes. This helps track why a task took longer than expected.\n\n### Step 7: Add Implementation Notes\n\n```bash\n# Add comprehensive notes (suitable for PR description)\nknowns task edit <id> --notes $\'## Summary\n\nImplemented JWT auth.\n\n## Changes\n- Added middleware\n- Added tests\'\n\n# OR append progressively (recommended)\nknowns task edit <id> --append-notes "\u2713 Implemented middleware"\nknowns task edit <id> --append-notes "\u2713 Added tests"\n```\n\n### Step 8: Stop Time Tracking (REQUIRED)\n\n```bash\nknowns time stop\n```\n\n> **CRITICAL**: Never forget to stop the timer. If you forget, use manual entry: `knowns time add <id> <duration> -n "Forgot to stop timer"`\n\n### Step 9: Complete Task\n\n```bash\nknowns task edit <id> -s done\n```\n\n### Step 10: Handle Post-Completion Changes (If Applicable)\n\nIf the user requests changes or updates AFTER task is marked done:\n\n```bash\n# 1. Reopen task - set back to in-progress\nknowns task edit <id> -s in-progress\n\n# 2. Restart time tracking (REQUIRED)\nknowns time start <id>\n\n# 3. Add new AC for the changes requested\nknowns task edit <id> --ac "Post-completion fix: <description>"\n\n# 4. Document the reopen reason\nknowns task edit <id> --append-notes "\u{1F504} Reopened: User requested changes - <reason>"\n\n# 5. Follow Step 5-9 again (Implement \u2192 Notes \u2192 Stop Timer \u2192 Done)\n```\n\n> **CRITICAL**: Treat post-completion changes as a mini-workflow. Always:\n> - Reopen task (in-progress)\n> - Start timer again\n> - Add AC for traceability\n> - Document why it was reopened\n> - Follow the same completion process\n\n### Step 11: Knowledge Extraction (Post-Completion)\n\nAfter completing a task, extract reusable knowledge to docs:\n\n```bash\n# Search if similar pattern already documented\nknowns search "<pattern/concept>" --type doc --plain\n\n# If new knowledge, create a doc for future reference\nknowns doc create "Pattern: <Name>" \\\n -d "Reusable pattern discovered during task implementation" \\\n -t "pattern,<domain>" \\\n -f "patterns"\n\n# Or append to existing doc\nknowns doc edit "<existing-doc>" -a "## New Section\\n\\nLearned from task <id>: ..."\n\n# Reference the source task\nknowns doc edit "<doc-name>" -a "\\n\\n> Source: @task-<id>"\n```\n\n**When to extract knowledge:**\n- New patterns/conventions discovered\n- Common error solutions\n- Reusable code snippets or approaches\n- Integration patterns with external services\n- Performance optimization techniques\n\n> **CRITICAL**: Only extract **generalizable** knowledge. Task-specific details belong in implementation notes, not docs.\n\n---\n\n## Essential Commands\n\n### Task Management\n\n```bash\n# Create task\nknowns task create "Title" -d "Description" --ac "Criterion" -l "labels" --priority high\n\n# Edit task\nknowns task edit <id> -t "New title"\nknowns task edit <id> -d "New description"\nknowns task edit <id> -s in-progress\nknowns task edit <id> --priority high\nknowns task edit <id> -a <assignee> # $(knowns config get defaultAssignee --plain || echo "@me")\n\n# Acceptance Criteria\nknowns task edit <id> --ac "New criterion" # Add\nknowns task edit <id> --check-ac 1 --check-ac 2 # Check (1-indexed)\nknowns task edit <id> --uncheck-ac 2 # Uncheck\nknowns task edit <id> --remove-ac 3 # Remove\n\n# Implementation Plan & Notes\nknowns task edit <id> --plan $\'1. Step\\n2. Step\'\nknowns task edit <id> --notes "Implementation summary"\nknowns task edit <id> --append-notes "Progress update"\n\n# View & List\nknowns task <id> --plain # Shorthand (ALWAYS use --plain)\nknowns task view <id> --plain # Full command\nknowns task list --plain\nknowns task list --status in-progress --plain\nknowns task list --assignee <assignee> --plain # $(knowns config get defaultAssignee --plain || echo "@me")\nknowns task list --tree --plain # Tree hierarchy\n```\n\n### Time Tracking\n\n```bash\n# Timer\nknowns time start <id>\nknowns time stop\nknowns time pause\nknowns time resume\nknowns time status\n\n# Manual entry\nknowns time add <id> 2h -n "Note" -d "2025-12-25"\n\n# Reports\nknowns time report --from "2025-12-01" --to "2025-12-31"\nknowns time report --by-label --csv > report.csv\n```\n\n### Documentation\n\n```bash\n# List & View\nknowns doc list --plain\nknowns doc list --tag architecture --plain\nknowns doc <path> --plain # Shorthand (ALWAYS use --plain)\nknowns doc view "<path>" --plain # Full command\n\n# Create (with optional folder)\nknowns doc create "Title" -d "Description" -t "tags"\nknowns doc create "Title" -d "Description" -t "tags" -f "folder/path"\n\n# Edit metadata\nknowns doc edit "Doc Name" -t "New Title" --tags "new,tags"\n\n# Edit content\nknowns doc edit "Doc Name" -c "New content" # Replace content\nknowns doc edit "Doc Name" -a "Appended content" # Append to content\n```\n\n#### Doc Organization\n\n| Doc Type | Location | Example |\n|----------|----------|---------|\n| **Important/Core docs** | Root `.knowns/docs/` | `README.md`, `ARCHITECTURE.md`, `CONVENTIONS.md` |\n| **Guides** | `.knowns/docs/guides/` | `guides/getting-started.md` |\n| **Patterns** | `.knowns/docs/patterns/` | `patterns/controller.md` |\n| **API docs** | `.knowns/docs/api/` | `api/endpoints.md` |\n| **Other categorized docs** | `.knowns/docs/<category>/` | `security/auth-patterns.md` |\n\n```bash\n# Important docs - at root (no -f flag)\nknowns doc create "README" -d "Project overview" -t "core"\nknowns doc create "ARCHITECTURE" -d "System design" -t "core"\n\n# Categorized docs - use -f for folder\nknowns doc create "Getting Started" -d "Setup guide" -t "guide" -f "guides"\nknowns doc create "Controller Pattern" -d "MVC pattern" -t "pattern" -f "patterns"\n```\n\n### Search\n\n```bash\n# Search everything\nknowns search "query" --plain\n\n# Search specific type\nknowns search "auth" --type task --plain\nknowns search "patterns" --type doc --plain\n\n# Filter\nknowns search "bug" --status in-progress --priority high --plain\n```\n\n---\n\n## Task Structure\n\n### Title\n\nClear summary (WHAT needs to be done).\n\n| Bad | 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\n\nExplains WHY and WHAT (not HOW). **Link related docs using `@doc/<path>`**\n\n```markdown\nWe need JWT authentication because sessions don\'t scale for our microservices architecture.\n\nRelated docs: @doc/security-patterns, @doc/api-guidelines\n```\n\n### Acceptance Criteria\n\n**Outcome-oriented**, testable criteria. NOT implementation steps.\n\n| Bad (Implementation details) | 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### Implementation Plan\n\nHOW to solve. Added AFTER taking task, BEFORE coding.\n\n```markdown\n1. Research JWT libraries (see @doc/security-patterns)\n2. Design token structure (access + refresh tokens)\n3. Implement auth middleware\n4. Add unit tests (aim for 90%+ coverage)\n5. Update API.md with new endpoints\n```\n\n### Implementation Notes\n\nSummary for PR description. Added AFTER completion.\n\n```markdown\n## Summary\nImplemented JWT auth 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## Documentation\n- Updated API.md with authentication section\n```\n\n---\n\n## Error Handling\n\n### Common Errors and Solutions\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| `Error: Task not found` | Invalid task ID | Run `knowns task list --plain` to find correct ID |\n| `Error: No active timer` | Calling `time stop` without active timer | Start timer first: `knowns time start <id>` |\n| `Error: Timer already running` | Starting timer when one is active | Stop current: `knowns time stop` |\n| `Error: Invalid status` | Wrong status format | Use lowercase with hyphens: `in-progress`, not `In Progress` |\n| `Error: AC index out of range` | Checking non-existent criterion | View task first: `knowns task <id> --plain` |\n| `Error: Document not found` | Wrong document name | Run `knowns doc list --plain` to find correct name |\n| `Error: Not initialized` | Running commands without init | Run `knowns init` first |\n\n### Debugging Commands\n\n```bash\n# Check CLI version\nknowns --version\n\n# Verify project is initialized\nknowns status\n\n# View raw task data (for debugging)\nknowns task <id> --json\n\n# Check timer status\nknowns time status\n```\n\n---\n\n## Definition of Done\n\nA task is **Done** ONLY when **ALL** criteria are met:\n\n### Via CLI (Required)\n\n- [ ] All acceptance criteria checked: `--check-ac <index>` (only after work is actually done)\n- [ ] Implementation notes added: `--notes "..."`\n- [ ] \u23F1\uFE0F Timer stopped: `knowns time stop` (MANDATORY - do not skip!)\n- [ ] Status set to done: `-s done`\n- [ ] Knowledge extracted to docs (if applicable)\n\n### Via Code (Required)\n\n- [ ] All tests pass\n- [ ] Documentation updated\n- [ ] Code reviewed (linting, formatting)\n- [ ] No regressions introduced\n\n---\n\n## Status & Priority Reference\n\n### Status Values\n\nUse **lowercase with hyphens**:\n\n| Status | Description | When to Use |\n|--------|-------------|-------------|\n| `todo` | Not started | Default for new tasks |\n| `in-progress` | Currently working | After taking task |\n| `in-review` | In code review | PR submitted |\n| `blocked` | Waiting on dependency | External blocker |\n| `done` | Completed | All criteria met |\n\n### Priority Values\n\n| Priority | Description |\n|----------|-------------|\n| `low` | Can wait, nice-to-have |\n| `medium` | Normal priority (default) |\n| `high` | Urgent, time-sensitive |\n\n---\n\n## Common Mistakes\n\n| Wrong | Right |\n|-------|-------|\n| Edit .md files directly | Use `knowns task edit` |\n| Change `- [ ]` to `- [x]` in file | Use `--check-ac <index>` |\n| Check AC before completing work | Only check AC AFTER work is actually done |\n| Skip time tracking | ALWAYS use `time start` and `time stop` |\n| Start coding without reading docs | Read ALL related docs FIRST |\n| Skip `knowns doc list` on new project | Always list docs when starting |\n| Assume you know the conventions | Read CONVENTIONS/ARCHITECTURE docs |\n| Plan without checking docs | Read docs before planning |\n| Ignore similar completed tasks | Search done tasks for patterns |\n| Missing doc links in description/plan | Link docs using `@doc/<path>` |\n| Write refs as `@.knowns/docs/...` or `@.knowns/tasks/...` | Use input format: `@doc/<path>`, `@task-<id>` |\n| Forget `--plain` flag | Always use `--plain` for AI |\n| Code before plan approval | Share plan, WAIT for approval |\n| Mark done without all criteria | Check ALL criteria first |\n| Write implementation steps in AC | Write outcome-oriented criteria |\n| Use `"In Progress"` or `"Done"` | Use `in-progress`, `done` |\n| Use `@yourself` or unknown assignee | Use `$(knowns config get defaultAssignee --plain \\|\\| echo "@me")` |\n| Ignore refs in task description | Follow ALL refs (`@.knowns/...`) before planning |\n| See `@.knowns/docs/...` but don\'t read | Use `knowns doc "<path>" --plain` |\n| See `@.knowns/tasks/task-X` but don\'t check | Use `knowns task X --plain` for context |\n| Follow only first-level refs | Recursively follow nested refs until complete |\n| Use `--plain` with `task create` | `--plain` is only for view/list commands |\n| Use `--plain` with `task edit` | `--plain` is only for view/list commands |\n| Use `--plain` with `doc create` | `--plain` is only for view/list commands |\n| Use `--plain` with `doc edit` | `--plain` is only for view/list commands |\n\n---\n\n## The `--plain` Flag (AI Agents)\n\n> **\u26A0\uFE0F CRITICAL FOR AI AGENTS**: The `--plain` flag is ONLY supported by **view/list/search** commands. Using it with create/edit commands will cause errors!\n\n### \u2705 Commands that support `--plain`\n\nThese are **read-only** commands - use `--plain` to get clean output:\n\n```bash\n# Task viewing/listing\nknowns task <id> --plain\nknowns task view <id> --plain\nknowns task list --plain\nknowns task list --status in-progress --plain\n\n# Doc viewing/listing\nknowns doc <path> --plain\nknowns doc view "<path>" --plain\nknowns doc list --plain\nknowns doc list --tag <tag> --plain\n\n# Search\nknowns search "<query>" --plain\nknowns search "<query>" --type task --plain\nknowns search "<query>" --type doc --plain\n\n# Config\nknowns config get <key> --plain\n```\n\n### \u274C Commands that do NOT support `--plain`\n\nThese are **write** commands - NEVER use `--plain`:\n\n```bash\n# Task create/edit - NO --plain!\nknowns task create "Title" -d "Description" # \u2705 Correct\nknowns task create "Title" --plain # \u274C ERROR!\nknowns task edit <id> -s done # \u2705 Correct\nknowns task edit <id> -s done --plain # \u274C ERROR!\n\n# Doc create/edit - NO --plain!\nknowns doc create "Title" -d "Description" # \u2705 Correct\nknowns doc create "Title" --plain # \u274C ERROR!\nknowns doc edit "name" -c "content" # \u2705 Correct\nknowns doc edit "name" -c "content" --plain # \u274C ERROR!\n\n# Time tracking - NO --plain!\nknowns time start <id> # \u2705 Correct\nknowns time stop # \u2705 Correct\nknowns time add <id> 2h # \u2705 Correct\n```\n\n### Quick Reference Table\n\n| Command Type | Example | `--plain` Support |\n|-------------|---------|-------------------|\n| `task <id>` | `knowns task 42 --plain` | \u2705 Yes |\n| `task list` | `knowns task list --plain` | \u2705 Yes |\n| `task create` | `knowns task create "Title"` | \u274C No |\n| `task edit` | `knowns task edit 42 -s done` | \u274C No |\n| `doc <path>` | `knowns doc "README" --plain` | \u2705 Yes |\n| `doc list` | `knowns doc list --plain` | \u2705 Yes |\n| `doc create` | `knowns doc create "Title"` | \u274C No |\n| `doc edit` | `knowns doc edit "name" -c "..."` | \u274C No |\n| `search` | `knowns search "query" --plain` | \u2705 Yes |\n| `time start/stop` | `knowns time start 42` | \u274C No |\n| `time add` | `knowns time add 42 2h` | \u274C No |\n| `config get` | `knowns config get key --plain` | \u2705 Yes |\n| `config set` | `knowns config set key value` | \u274C No |\n\n---\n\n## Platform-Specific Notes\n\n### Multi-line Input\n\nDifferent shells handle multi-line strings differently:\n\n**Bash / Zsh (Recommended)**\n```bash\nknowns task edit <id> --plan $\'1. First step\\n2. Second step\\n3. Third step\'\n```\n\n**PowerShell**\n```powershell\nknowns task edit <id> --plan "1. First step`n2. Second step`n3. Third step"\n```\n\n**Cross-platform (Using printf)**\n```bash\nknowns task edit <id> --plan "$(printf \'1. First step\\n2. Second step\\n3. Third step\')"\n```\n\n**Using heredoc (for long content)**\n```bash\nknowns task edit <id> --plan "$(cat <<EOF\n1. First step\n2. Second step\n3. Third step\nEOF\n)"\n```\n\n### Path Separators\n\n- **Unix/macOS**: Use forward slashes: `./docs/api.md`\n- **Windows**: Both work, but prefer forward slashes for consistency\n\n### Windows Command Line Limit\n\nWindows has ~8191 character limit. For long content, append in chunks:\n\n```bash\n# 1. Create or reset with short content\nknowns doc edit "doc-name" -c "## Overview\\n\\nShort intro."\n\n# 2. Append each section separately\nknowns doc edit "doc-name" -a "## Section 1\\n\\nContent..."\nknowns doc edit "doc-name" -a "## Section 2\\n\\nMore content..."\n```\n\nOr use file-based options:\n\n```bash\nknowns doc edit "doc-name" --content-file ./content.md\nknowns doc edit "doc-name" --append-file ./more.md\n```\n\n---\n\n## Best Practices Checklist\n\n### For AI Agents: Session Start\n\n- [ ] List all docs: `knowns doc list --plain`\n- [ ] Read README/ARCHITECTURE docs\n- [ ] Understand coding conventions\n- [ ] Review current task backlog\n\n### Before Starting Work\n\n- [ ] Task has clear acceptance criteria\n- [ ] ALL refs in task followed (`@.knowns/...`)\n- [ ] Nested refs recursively followed until complete context gathered\n- [ ] Related docs searched: `knowns search "keyword" --type doc --plain`\n- [ ] ALL relevant docs read: `knowns doc "Doc Name" --plain`\n- [ ] Similar done tasks reviewed for patterns\n- [ ] Task assigned to self: `-a $(knowns config get defaultAssignee --plain || echo "@me")`\n- [ ] Status set to in-progress: `-s in-progress`\n- [ ] Timer started: `knowns time start <id>`\n\n### During Work\n\n- [ ] Implementation plan created and approved\n- [ ] Doc links included in plan: `@doc/<path>`\n- [ ] Criteria checked as completed: `--check-ac <index>`\n- [ ] Progress notes appended: `--append-notes "\u2713 ..."`\n\n### After Work\n\n- [ ] All acceptance criteria checked (only after work is done)\n- [ ] Implementation notes added: `--notes "..."`\n- [ ] Timer stopped: `knowns time stop`\n- [ ] Tests passing\n- [ ] Documentation updated\n- [ ] Status set to done: `-s done`\n- [ ] Knowledge extracted to docs (if applicable): patterns, solutions, conventions\n\n---\n\n## Quick Reference Card\n\n```bash\n# === AGENT INITIALIZATION (Once per session) ===\nknowns doc list --plain\nknowns doc "README" --plain\nknowns doc "ARCHITECTURE" --plain\nknowns doc "CONVENTIONS" --plain\n\n# === FULL WORKFLOW ===\nknowns task create "Title" -d "Description" --ac "Criterion"\nknowns task edit <id> -s in-progress -a $(knowns config get defaultAssignee --plain || echo "@me")\nknowns time start <id> # \u23F1\uFE0F REQUIRED: Start timer\nknowns search "keyword" --type doc --plain\nknowns doc "Doc Name" --plain\nknowns search "keyword" --type task --status done --plain # Learn from history\nknowns task edit <id> --plan $\'1. Step (see @doc/file)\\n2. Step\'\n# ... wait for approval, then implement ...\n# Only check AC AFTER completing the work:\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "\u2713 Completed: feature X"\nknowns task edit <id> --check-ac 2\nknowns task edit <id> --append-notes "\u2713 Completed: feature Y"\nknowns time stop # \u23F1\uFE0F REQUIRED: Stop timer\nknowns task edit <id> -s done\n# Optional: Extract knowledge to docs if generalizable patterns found\n\n# === VIEW & SEARCH ===\nknowns task <id> --plain # Shorthand for view\nknowns task list --plain\nknowns task list --status in-progress --assignee $(knowns config get defaultAssignee --plain || echo "@me") --plain\nknowns search "query" --plain\nknowns search "bug" --type task --status in-progress --plain\n\n# === TIME TRACKING ===\nknowns time start <id>\nknowns time stop\nknowns time status\nknowns time report --from "2025-12-01" --to "2025-12-31"\n\n# === DOCUMENTATION ===\nknowns doc list --plain\nknowns doc "path/doc-name" --plain # Shorthand for view\nknowns doc create "Title" -d "Description" -t "tags" -f "folder"\nknowns doc edit "doc-name" -c "New content"\nknowns doc edit "doc-name" -a "Appended content"\n```\n\n---\n\n**Maintained By**: Knowns CLI Team\n\n<!-- KNOWNS GUIDELINES END -->\n';
|
|
43479
|
+
var general_default = '<!-- KNOWNS GUIDELINES START -->\n# Knowns CLI Guidelines\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n## Core Rules\n\n| Rule | Description |\n|------|-------------|\n| **CLI Only** | Use CLI commands for ALL operations. NEVER edit .md files directly |\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Always `time start` when taking task, `time stop` when done |\n| **--plain Flag** | Use `--plain` ONLY for view/list/search commands (NOT create/edit) |\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## Workflow\n\n### Session Start\n```bash\nknowns doc list --plain\nknowns doc "README" --plain\nknowns doc "ARCHITECTURE" --plain\nknowns doc "CONVENTIONS" --plain\n```\n\n### Task Lifecycle\n\n**1. Create & Take**\n```bash\nknowns task create "Title" -d "Description" --priority high -l "label1,label2"\nknowns task edit <id> -s in-progress -a @me\nknowns time start <id>\n```\n\n**2. Research**\n```bash\nknowns task <id> --plain # Follow ALL refs\nknowns search "keyword" --type doc --plain\nknowns doc "path/name" --plain\nknowns search "keyword" --type task --status done --plain\n```\n\n**3. Plan \u2192 Wait approval**\n```bash\nknowns task edit <id> --plan $\'1. Step (see @doc/xxx)\\n2. Step\'\n```\n\n**4. Implement**\n```bash\nknowns task edit <id> --append-notes "\u2713 Completed: feature X"\n```\n\n**5. Complete**\n```bash\nknowns time stop\nknowns task edit <id> -s done\n```\n\n---\n\n## Commands Quick Reference\n\n### Tasks\n```bash\nknowns task create "Title" -d "Desc" --priority high -l "labels" --parent <id>\nknowns task <id> --plain\nknowns task edit <id> -s <status> -a @me\nknowns task edit <id> --plan "..." --notes "..." --append-notes "..."\nknowns task edit <id> --check-ac 1 --check-ac 2\nknowns task list --plain\nknowns task list --status in-progress --plain\nknowns search "query" --type task --plain\n```\n\n### Time\n```bash\nknowns time start <id>\nknowns time stop\nknowns time add <id> 2h -n "Note"\nknowns time status\nknowns time report --from "2025-01-01" --to "2025-12-31"\n```\n\n### Docs\n```bash\nknowns doc list --plain\nknowns doc "path/name" --plain\nknowns doc create "Title" -d "Desc" -t "tags" -f "folder"\nknowns doc edit "name" -c "content"\nknowns doc edit "name" -a "append content"\nknowns search "query" --type doc --plain\n```\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**Subtasks:** Use raw ID \u2014 `--parent 48` not `--parent task-48`\n\n---\n\n## Status & Priority\n\n| Status | When |\n|--------|------|\n| `todo` | Not started |\n| `in-progress` | Working |\n| `in-review` | PR submitted |\n| `blocked` | Waiting |\n| `done` | Complete |\n\n| Priority | Level |\n|----------|-------|\n| `low` | Nice-to-have |\n| `medium` | Normal |\n| `high` | Urgent |\n\n---\n\n## Task Quality\n\n**Title**: Clear action\n\u274C "Fix bug" \u2192 \u2705 "Fix login timeout on slow networks"\n\n**Description**: WHY + WHAT, link docs with `@doc/path`\n\n**Acceptance**: Outcomes, not implementation\n\u274C "Add handleLogin()" \u2192 \u2705 "User can login and receive token"\n\n---\n\n## Common Mistakes\n\n| \u274C Wrong | \u2705 Right |\n|----------|----------|\n| Edit .md directly | Use CLI commands |\n| Skip timer | Always start/stop |\n| Code before docs | Read docs first |\n| Code before approval | Wait for approval |\n| `--parent task-48` | `--parent 48` |\n| Ignore refs | Follow ALL refs |\n| `--plain` with create/edit | `--plain` only for view/list/search |\n\n---\n\n## Definition of Done\n\n- [ ] Work completed\n- [ ] Notes added\n- [ ] Timer stopped\n- [ ] Tests passing\n- [ ] Docs updated\n- [ ] Status: done\n<!-- KNOWNS GUIDELINES END -->\n';
|
|
43483
43480
|
|
|
43484
|
-
// src/templates/
|
|
43485
|
-
var
|
|
43481
|
+
// src/templates/cli/instruction.md
|
|
43482
|
+
var instruction_default = "<!-- KNOWNS GUIDELINES START -->\n# Knowns Project\n\nThis project uses **Knowns CLI** for task and documentation management.\n\n## Before Starting\n\nRun this command to get usage guidelines:\n\n```bash\nknowns agents guideline\n```\n\nThis will output the complete rules for:\n- Task management workflow\n- Documentation commands\n- Time tracking\n- Reference system\n- Common mistakes to avoid\n\nYou MUST call this at session start and follow every rule it outputs. If any rule cannot be followed, stop and ask for guidance before proceeding.\n\n## Quick Commands\n\n```bash\n# Get guidelines (run this first!)\nknowns agents guideline\n\n# List tasks\nknowns task list --plain\n\n# List docs\nknowns doc list --plain\n```\n\n**Important:** Always read the guidelines before working on tasks.\n<!-- KNOWNS GUIDELINES END -->\n";
|
|
43486
43483
|
|
|
43487
43484
|
// src/templates/mcp/general.md
|
|
43488
|
-
var general_default2 = '<!-- KNOWNS GUIDELINES START -->\n# Knowns MCP Guidelines\n\n## Core Principles\n\n### 1. MCP Tool Operations\n**Use MCP tools for ALL Knowns operations. NEVER edit .md files directly.**\n\nThis ensures data integrity, maintains proper change history, and prevents file corruption.\n\n### 2. Documentation-First (For AI Agents)\n**ALWAYS read project documentation BEFORE planning or coding.**\n\nAI agents must understand project context, conventions, and existing patterns before making any changes. This prevents rework and ensures consistency.\n\n---\n\n## AI Agent Guidelines\n\n> **CRITICAL**: Before performing ANY task, AI agents MUST read documentation to understand project context.\n\n### First-Time Initialization\n\nWhen starting a new session or working on an unfamiliar project:\n\n```\n# 1. List all available documentation\nmcp__knowns__list_docs({})\n\n# 2. Read essential project docs (prioritize these)\nmcp__knowns__get_doc({ path: "README" })\nmcp__knowns__get_doc({ path: "ARCHITECTURE" })\nmcp__knowns__get_doc({ path: "CONVENTIONS" })\nmcp__knowns__get_doc({ path: "API" })\n\n# 3. Review current task backlog\nmcp__knowns__list_tasks({})\nmcp__knowns__list_tasks({ status: "in-progress" })\n```\n\n### Before Taking Any Task\n\n```\n# 1. View the task details\nmcp__knowns__get_task({ taskId: "<id>" })\n\n# 2. Follow ALL refs in the task (see Reference System section)\n# @.knowns/tasks/task-44 - ... \u2192 mcp__knowns__get_task({ taskId: "44" })\n# @.knowns/docs/patterns/module.md \u2192 mcp__knowns__get_doc({ path: "patterns/module" })\n\n# 3. Search for additional related documentation\nmcp__knowns__search_docs({ query: "<keywords from task>" })\n\n# 4. Read ALL related docs before planning\nmcp__knowns__get_doc({ path: "<related-doc>" })\n\n# 5. Check for similar completed tasks (learn from history)\nmcp__knowns__search_tasks({ query: "<keywords>", status: "done" })\n```\n\n### Why Documentation First?\n\n| Without Reading Docs | With Reading Docs |\n|---------------------|-------------------|\n| Reinvent existing patterns | Reuse established patterns |\n| Break conventions | Follow project standards |\n| Duplicate code | Use existing utilities |\n| Wrong architecture decisions | Align with system design |\n| Inconsistent naming | Match naming conventions |\n\n### Context Checklist for Agents\n\nBefore writing ANY code, ensure you can answer:\n\n- [ ] Have I followed ALL refs (`@.knowns/...`) in the task?\n- [ ] Have I followed nested refs recursively?\n- [ ] What is the project\'s overall architecture?\n- [ ] What coding conventions does this project follow?\n- [ ] Are there existing patterns/utilities I should reuse?\n- [ ] What are the testing requirements?\n- [ ] How should I structure my implementation?\n\n> **Remember**: A few minutes reading docs saves hours of rework. NEVER skip this step.\n\n---\n\n## Reference System (Refs)\n\nTasks and docs can contain **references** to other tasks/docs. AI agents MUST understand and follow these refs to gather complete context.\n\n### Reference Formats\n\n| Type | When Writing (Input) | When Reading (Output) | MCP Tool |\n|------|---------------------|----------------------|----------|\n| **Task ref** | `@task-<id>` | `@.knowns/tasks/task-<id> - <title>.md` | `mcp__knowns__get_task({ taskId: "<id>" })` |\n| **Doc ref** | `@doc/<path>` | `@.knowns/docs/<path>.md` | `mcp__knowns__get_doc({ path: "<path>" })` |\n\n> **CRITICAL for AI Agents**:\n> - When **WRITING** refs (in descriptions, plans, notes): Use `@task-<id>` and `@doc/<path>`\n> - When **READING** output: You\'ll see `@.knowns/tasks/...` and `@.knowns/docs/...`\n> - **NEVER write** the output format (`@.knowns/...`) - always use input format\n\n### How to Follow Refs\n\nWhen you read a task and see refs in system output format, follow them:\n\n```\n# Example: Task 42 output contains:\n# @.knowns/tasks/task-44 - CLI Task Create Command.md\n# @.knowns/docs/patterns/module.md\n\n# Follow task ref (extract ID from task-<id>)\nmcp__knowns__get_task({ taskId: "44" })\n\n# Follow doc ref (extract path, remove .md)\nmcp__knowns__get_doc({ path: "patterns/module" })\n```\n\n### Recursive Following\n\nRefs can be nested. Follow until complete context is gathered:\n\n```\nTask 42\n \u2192 @.knowns/docs/README.md\n \u2192 @.knowns/docs/patterns/module.md (found in README)\n \u2192 (read for full pattern details)\n```\n\n> **CRITICAL**: Never assume you understand a task fully without following its refs. Refs contain essential context that may change your implementation approach.\n\n---\n\n## Quick Start\n\n```\n# Initialize project (use CLI for this)\nknowns init [name]\n\n# Create task with acceptance criteria\nmcp__knowns__create_task({\n title: "Title",\n description: "Description",\n priority: "high",\n labels: ["label1", "label2"]\n})\n\n# View task\nmcp__knowns__get_task({ taskId: "<id>" })\n\n# List tasks\nmcp__knowns__list_tasks({})\n\n# Search (tasks + docs)\nmcp__knowns__search_tasks({ query: "query" })\nmcp__knowns__search_docs({ query: "query" })\n```\n\n---\n\n## End-to-End Example\n\nHere\'s a complete workflow for an AI agent implementing a feature:\n\n```\n# === AGENT SESSION START (Do this once per session) ===\n\n# 0a. List all available documentation\nmcp__knowns__list_docs({})\n\n# 0b. Read essential project docs\nmcp__knowns__get_doc({ path: "README" })\nmcp__knowns__get_doc({ path: "ARCHITECTURE" })\nmcp__knowns__get_doc({ path: "CONVENTIONS" })\n\n# Now the agent understands project context and conventions\n\n# === TASK WORKFLOW ===\n\n# 1. Create the task\nmcp__knowns__create_task({\n title: "Add password reset flow",\n description: "Users need ability to reset forgotten passwords via email",\n priority: "high",\n labels: ["auth", "feature"]\n})\n\n# Output: Created task 42\n\n# 2. Take the task and start timer\nmcp__knowns__update_task({\n taskId: "42",\n status: "in-progress",\n assignee: "@howznguyen"\n})\nmcp__knowns__start_time({ taskId: "42" })\n\n# 3. Search for related documentation\nmcp__knowns__search_docs({ query: "password security" })\n\n# 4. Read the documentation\nmcp__knowns__get_doc({ path: "security-patterns" })\n\n# 5. Create implementation plan (SHARE WITH USER, WAIT FOR APPROVAL)\nmcp__knowns__update_task({\n taskId: "42",\n plan: "1. Review security patterns (see @doc/security-patterns)\\n2. Design token generation with 1-hour expiry\\n3. Implement /forgot-password endpoint\\n4. Add unit tests"\n})\n\n# 6. After approval, implement and update task progressively\nmcp__knowns__update_task({\n taskId: "42",\n appendNotes: "\u2713 Implemented /forgot-password endpoint"\n})\n\n# 7. Add final implementation notes\nmcp__knowns__update_task({\n taskId: "42",\n notes: "## Summary\\nImplemented complete password reset flow.\\n\\n## Changes\\n- Added POST /forgot-password endpoint\\n- Added POST /reset-password endpoint"\n})\n\n# 8. Stop timer and complete\nmcp__knowns__stop_time({ taskId: "42" })\nmcp__knowns__update_task({\n taskId: "42",\n status: "done"\n})\n```\n\n---\n\n## Task Workflow\n\n### Step 1: Take Task\n\n```\n# Update task status and assign to self\nmcp__knowns__update_task({\n taskId: "<id>",\n status: "in-progress",\n assignee: "@<your-username>"\n})\n```\n\n> **Note**: Use your username as configured in the project. Check project config for `defaultAssignee`.\n\n### Step 2: Start Time Tracking (REQUIRED)\n\n```\nmcp__knowns__start_time({ taskId: "<id>" })\n```\n\n> **CRITICAL**: Time tracking is MANDATORY. Always start timer when taking a task and stop when done. This data is essential for:\n> - Accurate project estimation\n> - Identifying bottlenecks\n> - Resource planning\n> - Sprint retrospectives\n\n### Step 3: Read Related Documentation\n\n> **FOR AI AGENTS**: This step is MANDATORY, not optional. You must understand the codebase before planning.\n\n```\n# Search for related docs\nmcp__knowns__search_docs({ query: "authentication" })\n\n# View relevant documents\nmcp__knowns__get_doc({ path: "API Guidelines" })\nmcp__knowns__get_doc({ path: "Security Patterns" })\n\n# Also check for similar completed tasks\nmcp__knowns__search_tasks({ query: "auth", status: "done" })\n```\n\n> **CRITICAL**: ALWAYS read related documentation BEFORE planning!\n\n### Step 4: Create Implementation Plan\n\n```\nmcp__knowns__update_task({\n taskId: "<id>",\n plan: "1. Research patterns (see @doc/security-patterns)\\n2. Design middleware\\n3. Implement\\n4. Add tests\\n5. Update docs"\n})\n```\n\n> **CRITICAL**:\n> - Share plan with user and **WAIT for approval** before coding\n> - Include doc references using `@doc/<path>` format\n\n### Step 5: Implement\n\n```\n# Work through implementation plan step by step\n# IMPORTANT: Only update task AFTER completing the work, not before\n\n# After completing work, append notes:\nmcp__knowns__update_task({\n taskId: "<id>",\n appendNotes: "\u2713 Completed: <brief description>"\n})\n```\n\n> **CRITICAL**: Never claim work is done before it\'s actually completed.\n\n### Step 6: Handle Dynamic Requests (During Implementation)\n\nIf the user adds new requirements during implementation:\n\n```\n# Append note about scope change\nmcp__knowns__update_task({\n taskId: "<id>",\n appendNotes: "\u26A0\uFE0F Scope updated: Added requirement for X per user request"\n})\n\n# Continue with Step 5 (Implement) for new requirements\n```\n\n> **Note**: Always document scope changes. This helps track why a task took longer than expected.\n\n### Step 7: Add Implementation Notes\n\n```\n# Add comprehensive notes (suitable for PR description)\nmcp__knowns__update_task({\n taskId: "<id>",\n notes: "## Summary\\n\\nImplemented JWT auth.\\n\\n## Changes\\n- Added middleware\\n- Added tests"\n})\n\n# OR append progressively (recommended)\nmcp__knowns__update_task({\n taskId: "<id>",\n appendNotes: "\u2713 Implemented middleware"\n})\n```\n\n### Step 8: Stop Time Tracking (REQUIRED)\n\n```\nmcp__knowns__stop_time({ taskId: "<id>" })\n```\n\n> **CRITICAL**: Never forget to stop the timer. If you forget, use manual entry:\n> `mcp__knowns__add_time({ taskId: "<id>", duration: "2h", note: "Forgot to stop timer" })`\n\n### Step 9: Complete Task\n\n```\nmcp__knowns__update_task({\n taskId: "<id>",\n status: "done"\n})\n```\n\n### Step 10: Handle Post-Completion Changes (If Applicable)\n\nIf the user requests changes or updates AFTER task is marked done:\n\n```\n# 1. Reopen task - set back to in-progress\nmcp__knowns__update_task({\n taskId: "<id>",\n status: "in-progress"\n})\n\n# 2. Restart time tracking (REQUIRED)\nmcp__knowns__start_time({ taskId: "<id>" })\n\n# 3. Document the reopen reason\nmcp__knowns__update_task({\n taskId: "<id>",\n appendNotes: "\u{1F504} Reopened: User requested changes - <reason>"\n})\n\n# 4. Follow Step 5-9 again (Implement \u2192 Notes \u2192 Stop Timer \u2192 Done)\n```\n\n> **CRITICAL**: Treat post-completion changes as a mini-workflow. Always:\n> - Reopen task (in-progress)\n> - Start timer again\n> - Document why it was reopened\n> - Follow the same completion process\n\n### Step 11: Knowledge Extraction (Post-Completion)\n\nAfter completing a task, extract reusable knowledge to docs:\n\n```\n# Search if similar pattern already documented\nmcp__knowns__search_docs({ query: "<pattern/concept>" })\n\n# If new knowledge, create a doc for future reference\nmcp__knowns__create_doc({\n title: "Pattern: <Name>",\n description: "Reusable pattern discovered during task implementation",\n tags: ["pattern", "<domain>"],\n folder: "patterns"\n})\n\n# Or append to existing doc\nmcp__knowns__update_doc({\n path: "<existing-doc>",\n appendContent: "## New Section\\n\\nLearned from task <id>: ..."\n})\n```\n\n**When to extract knowledge:**\n- New patterns/conventions discovered\n- Common error solutions\n- Reusable code snippets or approaches\n- Integration patterns with external services\n- Performance optimization techniques\n\n> **CRITICAL**: Only extract **generalizable** knowledge. Task-specific details belong in implementation notes, not docs.\n\n---\n\n## Essential MCP Tools\n\n### Task Management\n\n```\n# Create task\nmcp__knowns__create_task({\n title: "Title",\n description: "Description",\n priority: "high", # low, medium, high\n labels: ["label1"],\n status: "todo", # todo, in-progress, in-review, done, blocked\n assignee: "@username"\n})\n\n# Get task\nmcp__knowns__get_task({ taskId: "<id>" })\n\n# Update task\nmcp__knowns__update_task({\n taskId: "<id>",\n title: "New title",\n description: "New description",\n status: "in-progress",\n priority: "high",\n assignee: "@username",\n labels: ["new", "labels"],\n plan: "Implementation plan...",\n notes: "Implementation notes...",\n appendNotes: "Append to existing notes..."\n})\n\n# List tasks\nmcp__knowns__list_tasks({})\nmcp__knowns__list_tasks({ status: "in-progress" })\nmcp__knowns__list_tasks({ assignee: "@username" })\nmcp__knowns__list_tasks({ priority: "high" })\nmcp__knowns__list_tasks({ label: "feature" })\n\n# Search tasks\nmcp__knowns__search_tasks({ query: "auth" })\n```\n\n### Time Tracking\n\n```\n# Start timer\nmcp__knowns__start_time({ taskId: "<id>" })\n\n# Stop timer\nmcp__knowns__stop_time({ taskId: "<id>" })\n\n# Manual entry\nmcp__knowns__add_time({\n taskId: "<id>",\n duration: "2h", # e.g., "2h", "30m", "1h30m"\n note: "Optional note",\n date: "2025-12-25" # Optional, defaults to now\n})\n\n# Reports\nmcp__knowns__get_time_report({})\nmcp__knowns__get_time_report({\n from: "2025-12-01",\n to: "2025-12-31",\n groupBy: "task" # task, label, status\n})\n```\n\n### Documentation\n\n```\n# List docs\nmcp__knowns__list_docs({})\nmcp__knowns__list_docs({ tag: "architecture" })\n\n# Get doc\nmcp__knowns__get_doc({ path: "README" })\nmcp__knowns__get_doc({ path: "patterns/module" })\n\n# Create doc\nmcp__knowns__create_doc({\n title: "Title",\n description: "Description",\n tags: ["tag1", "tag2"],\n folder: "folder/path", # Optional\n content: "Initial content..."\n})\n\n# Update doc\nmcp__knowns__update_doc({\n path: "doc-name",\n title: "New Title",\n description: "New description",\n tags: ["new", "tags"],\n content: "Replace content...",\n appendContent: "Append to content..."\n})\n\n# Search docs\nmcp__knowns__search_docs({ query: "patterns" })\nmcp__knowns__search_docs({ query: "auth", tag: "security" })\n```\n\n#### Doc Organization\n\n| Doc Type | Location | Example |\n|----------|----------|---------|\n| **Important/Core docs** | Root `.knowns/docs/` | `README.md`, `ARCHITECTURE.md`, `CONVENTIONS.md` |\n| **Guides** | `.knowns/docs/guides/` | `guides/getting-started.md` |\n| **Patterns** | `.knowns/docs/patterns/` | `patterns/controller.md` |\n| **API docs** | `.knowns/docs/api/` | `api/endpoints.md` |\n| **Other categorized docs** | `.knowns/docs/<category>/` | `security/auth-patterns.md` |\n\n```\n# Important docs - at root (no folder)\nmcp__knowns__create_doc({ title: "README", description: "Project overview", tags: ["core"] })\nmcp__knowns__create_doc({ title: "ARCHITECTURE", description: "System design", tags: ["core"] })\n\n# Categorized docs - use folder\nmcp__knowns__create_doc({ title: "Getting Started", description: "Setup guide", tags: ["guide"], folder: "guides" })\nmcp__knowns__create_doc({ title: "Controller Pattern", description: "MVC pattern", tags: ["pattern"], folder: "patterns" })\n```\n\n### Board\n\n```\n# Get kanban board view\nmcp__knowns__get_board({})\n```\n\n---\n\n## Task Structure\n\n### Title\n\nClear summary (WHAT needs to be done).\n\n| Bad | 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\n\nExplains WHY and WHAT (not HOW). **Link related docs using `@doc/<path>`**\n\n```\nWe need JWT authentication because sessions don\'t scale for our microservices architecture.\n\nRelated docs: @doc/security-patterns, @doc/api-guidelines\n```\n\n### Acceptance Criteria\n\n**Outcome-oriented**, testable criteria. NOT implementation steps.\n\n| Bad (Implementation details) | 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## Definition of Done\n\nA task is **Done** ONLY when **ALL** criteria are met:\n\n### Via MCP Tools (Required)\n\n- [ ] All work completed and verified\n- [ ] Implementation notes added via `update_task`\n- [ ] \u23F1\uFE0F Timer stopped: `mcp__knowns__stop_time` (MANDATORY - do not skip!)\n- [ ] Status set to done via `update_task`\n- [ ] Knowledge extracted to docs (if applicable)\n\n### Via Code (Required)\n\n- [ ] All tests pass\n- [ ] Documentation updated\n- [ ] Code reviewed (linting, formatting)\n- [ ] No regressions introduced\n\n---\n\n## Status & Priority Reference\n\n### Status Values\n\n| Status | Description | When to Use |\n|--------|-------------|-------------|\n| `todo` | Not started | Default for new tasks |\n| `in-progress` | Currently working | After taking task |\n| `in-review` | In code review | PR submitted |\n| `blocked` | Waiting on dependency | External blocker |\n| `done` | Completed | All criteria met |\n\n### Priority Values\n\n| Priority | Description |\n|----------|-------------|\n| `low` | Can wait, nice-to-have |\n| `medium` | Normal priority (default) |\n| `high` | Urgent, time-sensitive |\n\n---\n\n## Common Mistakes\n\n| Wrong | Right |\n|-------|-------|\n| Edit .md files directly | Use MCP tools |\n| Skip time tracking | ALWAYS use `start_time` and `stop_time` |\n| Start coding without reading docs | Read ALL related docs FIRST |\n| Plan without checking docs | Read docs before planning |\n| Code before plan approval | Share plan, WAIT for approval |\n| Mark done without all criteria | Verify ALL criteria first |\n| Ignore refs in task description | Follow ALL refs before planning |\n| Follow only first-level refs | Recursively follow nested refs |\n\n---\n\n## Long Content Handling\n\nFor long documentation content, append in chunks:\n\n```\n# 1. Create doc with initial content\nmcp__knowns__create_doc({\n title: "Doc Title",\n content: "## Overview\\n\\nShort intro."\n})\n\n# 2. Append each section separately\nmcp__knowns__update_doc({\n path: "doc-title",\n appendContent: "## Section 1\\n\\nContent for section 1..."\n})\n\nmcp__knowns__update_doc({\n path: "doc-title",\n appendContent: "## Section 2\\n\\nContent for section 2..."\n})\n```\n\n> **Tip**: Each `appendContent` adds content after existing content. Use this for large docs to avoid context limits.\n\n---\n\n## Best Practices Checklist\n\n### For AI Agents: Session Start\n\n- [ ] List all docs: `mcp__knowns__list_docs({})`\n- [ ] Read README/ARCHITECTURE docs\n- [ ] Understand coding conventions\n- [ ] Review current task backlog\n\n### Before Starting Work\n\n- [ ] Task details retrieved: `mcp__knowns__get_task`\n- [ ] ALL refs in task followed\n- [ ] Nested refs recursively followed\n- [ ] Related docs searched and read\n- [ ] Similar done tasks reviewed for patterns\n- [ ] Task assigned to self via `update_task`\n- [ ] Status set to in-progress\n- [ ] Timer started: `mcp__knowns__start_time`\n\n### During Work\n\n- [ ] Implementation plan created and approved\n- [ ] Doc links included in plan: `@doc/<path>`\n- [ ] Progress notes appended: `appendNotes`\n\n### After Work\n\n- [ ] All work verified complete\n- [ ] Implementation notes added\n- [ ] Timer stopped: `mcp__knowns__stop_time`\n- [ ] Tests passing\n- [ ] Documentation updated\n- [ ] Status set to done\n- [ ] Knowledge extracted to docs (if applicable)\n\n---\n\n## Quick Reference\n\n```\n# === AGENT INITIALIZATION (Once per session) ===\nmcp__knowns__list_docs({})\nmcp__knowns__get_doc({ path: "README" })\nmcp__knowns__get_doc({ path: "ARCHITECTURE" })\nmcp__knowns__get_doc({ path: "CONVENTIONS" })\n\n# === FULL WORKFLOW ===\nmcp__knowns__create_task({ title: "Title", description: "Description" })\nmcp__knowns__update_task({ taskId: "<id>", status: "in-progress", assignee: "@me" })\nmcp__knowns__start_time({ taskId: "<id>" }) # \u23F1\uFE0F REQUIRED\nmcp__knowns__search_docs({ query: "keyword" })\nmcp__knowns__get_doc({ path: "Doc Name" })\nmcp__knowns__search_tasks({ query: "keyword", status: "done" }) # Learn from history\nmcp__knowns__update_task({ taskId: "<id>", plan: "1. Step\\n2. Step" })\n# ... wait for approval, then implement ...\nmcp__knowns__update_task({ taskId: "<id>", appendNotes: "\u2713 Completed: feature X" })\nmcp__knowns__stop_time({ taskId: "<id>" }) # \u23F1\uFE0F REQUIRED\nmcp__knowns__update_task({ taskId: "<id>", status: "done" })\n# Optional: Extract knowledge to docs if generalizable patterns found\n\n# === VIEW & SEARCH ===\nmcp__knowns__get_task({ taskId: "<id>" })\nmcp__knowns__list_tasks({})\nmcp__knowns__list_tasks({ status: "in-progress", assignee: "@me" })\nmcp__knowns__search_tasks({ query: "bug" })\nmcp__knowns__search_docs({ query: "pattern" })\n\n# === TIME TRACKING ===\nmcp__knowns__start_time({ taskId: "<id>" })\nmcp__knowns__stop_time({ taskId: "<id>" })\nmcp__knowns__add_time({ taskId: "<id>", duration: "2h" })\nmcp__knowns__get_time_report({})\n\n# === DOCUMENTATION ===\nmcp__knowns__list_docs({})\nmcp__knowns__get_doc({ path: "path/doc-name" })\nmcp__knowns__create_doc({ title: "Title", description: "Desc", tags: ["tag"] })\nmcp__knowns__update_doc({ path: "doc-name", appendContent: "New content" })\n```\n\n---\n\n**Maintained By**: Knowns CLI Team\n\n<!-- KNOWNS GUIDELINES END -->\n';
|
|
43485
|
+
var general_default2 = '<!-- KNOWNS GUIDELINES START -->\n# Knowns MCP Guidelines\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n## Core Rules\n\n| Rule | Description |\n|------|-------------|\n| **MCP Only** | Use MCP tools for ALL operations. NEVER edit .md files directly |\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Always `start_time` when taking task, `stop_time` when done |\n| **Fallback to CLI** | If an MCP tool is missing, run the equivalent CLI command instead |\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## Workflow\n\n### Session Start\n```\nlist_docs({})\nget_doc({ path: "README" })\nget_doc({ path: "ARCHITECTURE" })\nget_doc({ path: "CONVENTIONS" })\n```\n\n### Task Lifecycle\n\n**1. Create & Take**\n```\ncreate_task({ title, description, priority, labels })\nupdate_task({ taskId, status: "in-progress", assignee: "@username" })\nstart_time({ taskId })\n```\n\n**2. Research**\n```\nget_task({ taskId }) # Follow ALL refs\nsearch_docs({ query })\nget_doc({ path })\nsearch_tasks({ query, status: "done" })\n```\n\n**3. Plan \u2192 Wait approval**\n```\nupdate_task({ taskId, plan: "1. Step (see @doc/xxx)\\n2. Step" })\n```\n\n**4. Implement**\n```\nupdate_task({ taskId, appendNotes: "\u2713 Completed: feature X" })\n```\n\n**5. Complete**\n```\nstop_time({ taskId })\nupdate_task({ taskId, status: "done" })\n```\n\n---\n\n## Tools Quick Reference\n\n### Tasks\n- `create_task({ title, description, priority?, labels?, parent? })`\n- `get_task({ taskId })`\n- `update_task({ taskId, status?, plan?, notes?, appendNotes? })`\n- `list_tasks({ status?, assignee?, label? })`\n- `search_tasks({ query, status? })`\n\n### Time\n- `start_time({ taskId })`\n- `stop_time({ taskId })`\n- `add_time({ taskId, duration, note? })` \u2014 duration: "2h", "30m"\n- `get_time_report({ from?, to?, groupBy? })`\n\n### Docs\n- `list_docs({ tag? })`\n- `get_doc({ path })` \u2014 path without .md\n- `create_doc({ title, description, tags?, folder?, content? })`\n- `update_doc({ path, content?, appendContent? })`\n- `search_docs({ query, tag? })`\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**Subtasks:** Use raw ID \u2014 `parent: "48"` not `parent: "task-48"`\n\n---\n\n## Status & Priority\n\n| Status | When |\n|--------|------|\n| `todo` | Not started |\n| `in-progress` | Working |\n| `in-review` | PR submitted |\n| `blocked` | Waiting |\n| `done` | Complete |\n\n| Priority | Level |\n|----------|-------|\n| `low` | Nice-to-have |\n| `medium` | Normal |\n| `high` | Urgent |\n\n---\n\n## Task Quality\n\n**Title**: Clear action\n\u274C "Fix bug" \u2192 \u2705 "Fix login timeout on slow networks"\n\n**Description**: WHY + WHAT, link docs with `@doc/path`\n\n**Acceptance**: Outcomes, not implementation\n\u274C "Add handleLogin()" \u2192 \u2705 "User can login and receive token"\n\n---\n\n## Common Mistakes\n\n| \u274C Wrong | \u2705 Right |\n|----------|----------|\n| Edit .md directly | Use MCP tools |\n| Skip timer | Always start/stop |\n| Code before docs | Read docs first |\n| Code before approval | Wait for approval |\n| `parent: "task-48"` | `parent: "48"` |\n| Ignore refs | Follow ALL refs |\n\n---\n\n## Definition of Done\n\n- [ ] Work completed\n- [ ] Notes added\n- [ ] Timer stopped\n- [ ] Tests passing\n- [ ] Docs updated\n- [ ] Status: done\n<!-- KNOWNS GUIDELINES END -->\n';
|
|
43486
|
+
|
|
43487
|
+
// src/templates/mcp/instruction.md
|
|
43488
|
+
var instruction_default2 = '<!-- KNOWNS GUIDELINES START -->\n# Knowns Project\n\nThis project uses **Knowns MCP** tools for task and documentation management.\n\n## Before Starting\n\nCall this MCP tool to get usage guidelines:\n\n```\nmcp__knowns__get_guideline({})\n```\n\nThis will return the complete rules for:\n- Task management workflow\n- Documentation commands\n- Time tracking\n- Reference system\n- Common mistakes to avoid\n- MCP tools unavailable? Use the equivalent CLI command as a fallback.\n\nYou MUST call this at session start and follow every rule it returns. If you cannot follow a rule, stop and ask for guidance before proceeding.\n\n**Fallback:** If any MCP tool is missing or fails, first run `knowns agents guideline --cli` to load the CLI rules, then switch to the matching CLI command (e.g., `knowns task list --plain`, `knowns doc "README" --plain`) and continue.\n\n## Quick Tools\n\n```\n// Get guidelines (call this first!)\nmcp__knowns__get_guideline({})\n\n// List tasks\nmcp__knowns__list_tasks({})\n\n// List docs\nmcp__knowns__list_docs({})\n```\n\n**Important:** Always read the guidelines before working on tasks.\n<!-- KNOWNS GUIDELINES END -->\n';
|
|
43489
|
+
|
|
43490
|
+
// src/templates/unified.md
|
|
43491
|
+
var unified_default = '# Knowns Guidelines\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n## Core Rules\n\n| Rule | Description |\n|------|-------------|\n| **Never Edit .md** | Use CLI commands or MCP tools. 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| **MCP \u2192 CLI Fallback** | If an MCP tool is missing, run the equivalent CLI command instead |\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> - Title.md` | `@.knowns/docs/<path>.md` |\n\nWhen reading refs in output, extract ID/path and call appropriate tool. Follow refs recursively.\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`, `a7f3k9` | Current (6-char base36) |\n\n**Subtasks:** Use raw ID for parent (NOT "task-48")\n\n---\n\n## Workflow\n\n### Session Start\n1. List docs \u2192 Read README, ARCHITECTURE, CONVENTIONS\n2. Review task backlog\n\n### Task Lifecycle\n1. **Take**: Set status `in-progress`, assign, start timer\n2. **Research**: Get task details, follow ALL refs, search related docs\n3. **Plan**: Create plan with doc refs \u2192 Wait for approval\n4. **Implement**: Work step by step, append progress notes\n5. **Complete**: Stop timer, set status `done`\n\n### Post-Completion Changes\nReopen (in-progress) \u2192 Start timer \u2192 Document reason \u2192 Implement \u2192 Complete\n\n---\n\n## Command Reference\n\n### Task Commands\n| Action | CLI | MCP |\n|--------|-----|-----|\n| Create | `knowns task create "T" -d "D" --priority high` | `create_task({ title, description, priority })` |\n| Create Subtask | `knowns task create "T" --parent 48` | `create_task({ title, parent: "48" })` |\n| View | `knowns task <id> --plain` | `get_task({ taskId })` |\n| List | `knowns task list --plain` | `list_tasks({})` |\n| Update | `knowns task edit <id> -s done` | `update_task({ taskId, status: "done" })` |\n| Search | `knowns search "q" --type task --plain` | `search_tasks({ query })` |\n\n### Doc Commands\n| Action | CLI | MCP |\n|--------|-----|-----|\n| List | `knowns doc list --plain` | `list_docs({})` |\n| View | `knowns doc "path" --plain` | `get_doc({ path })` |\n| Create | `knowns doc create "T" -d "D" -f "folder"` | `create_doc({ title, description, folder })` |\n| Update | `knowns doc edit "name" -a "content"` | `update_doc({ path, appendContent })` |\n| Search | `knowns search "q" --type doc --plain` | `search_docs({ query })` |\n\n### Time Commands\n| Action | CLI | MCP |\n|--------|-----|-----|\n| Start | `knowns time start <id>` | `start_time({ taskId })` |\n| Stop | `knowns time stop` | `stop_time({ taskId })` |\n| Add | `knowns time add <id> 2h -n "Note"` | `add_time({ taskId, duration, note })` |\n\n---\n\n## Status & Priority\n\n| Status | Use 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 | Description |\n|----------|-------------|\n| `low` | Nice-to-have |\n| `medium` | Normal (default) |\n| `high` | Urgent |\n\n---\n\n## CLI Notes\n\n- Use `--plain` flag ONLY for view/list/search commands (NOT create/edit)\n- Multi-line: `$\'line1\\nline2\'` (bash) or heredoc\n\n---\n\n## Common Mistakes\n\n| \u274C Wrong | \u2705 Right |\n|----------|----------|\n| Edit .md files directly | Use CLI/MCP tools |\n| Skip time tracking | Always start/stop timer |\n| Code before reading docs | Read ALL related docs first |\n| Code before plan approval | Wait for user approval |\n| `--parent task-48` | `--parent 48` (raw ID only) |\n| Ignore refs in task | Follow ALL refs recursively |\n| `--plain` with create/edit | `--plain` only for view/list/search |\n\n---\n\n## Definition of Done\n\n- [ ] All work completed and verified\n- [ ] Implementation notes added\n- [ ] Timer stopped\n- [ ] Tests passing\n- [ ] Documentation updated\n- [ ] Status set to done\n';
|
|
43489
43492
|
|
|
43490
43493
|
// src/commands/agents.ts
|
|
43491
43494
|
var PROJECT_ROOT = process.cwd();
|
|
@@ -43495,11 +43498,11 @@ var INSTRUCTION_FILES = [
|
|
|
43495
43498
|
{ path: "GEMINI.md", name: "Gemini", selected: false },
|
|
43496
43499
|
{ path: ".github/copilot-instructions.md", name: "GitHub Copilot", selected: false }
|
|
43497
43500
|
];
|
|
43498
|
-
function getGuidelines(type, variant = "
|
|
43501
|
+
function getGuidelines(type, variant = "instruction") {
|
|
43499
43502
|
if (type === "mcp") {
|
|
43500
|
-
return variant === "
|
|
43503
|
+
return variant === "instruction" ? instruction_default2 : general_default2;
|
|
43501
43504
|
}
|
|
43502
|
-
return variant === "
|
|
43505
|
+
return variant === "instruction" ? instruction_default : general_default;
|
|
43503
43506
|
}
|
|
43504
43507
|
async function updateInstructionFile(filePath, guidelines) {
|
|
43505
43508
|
const fullPath = join3(PROJECT_ROOT, filePath);
|
|
@@ -43530,11 +43533,11 @@ ${guidelines}
|
|
|
43530
43533
|
await writeFile2(fullPath, newContent, "utf-8");
|
|
43531
43534
|
return { success: true, action: "updated" };
|
|
43532
43535
|
}
|
|
43533
|
-
var agentsCommand = new Command("agents").description("Manage agent instruction files (CLAUDE.md, GEMINI.md, etc.)").enablePositionalOptions().passThroughOptions().option("--update-instructions", "Update agent instruction files (non-interactive)").option("--type <type>", "Guidelines type: cli or mcp", "cli").option("--
|
|
43536
|
+
var agentsCommand = new Command("agents").description("Manage agent instruction files (CLAUDE.md, GEMINI.md, etc.)").enablePositionalOptions().passThroughOptions().option("--update-instructions", "Update agent instruction files (non-interactive)").option("--type <type>", "Guidelines type: cli or mcp", "cli").option("--files <files>", "Comma-separated list of files to update").action(async (options2) => {
|
|
43534
43537
|
try {
|
|
43535
43538
|
if (options2.updateInstructions) {
|
|
43536
43539
|
const type = options2.type === "mcp" ? "mcp" : "cli";
|
|
43537
|
-
const variant =
|
|
43540
|
+
const variant = "general";
|
|
43538
43541
|
const guidelines2 = getGuidelines(type, variant);
|
|
43539
43542
|
let filesToUpdate = INSTRUCTION_FILES;
|
|
43540
43543
|
if (options2.files) {
|
|
@@ -43543,7 +43546,7 @@ var agentsCommand = new Command("agents").description("Manage agent instruction
|
|
|
43543
43546
|
(f) => requestedFiles.includes(f.path) || requestedFiles.includes(f.name)
|
|
43544
43547
|
);
|
|
43545
43548
|
}
|
|
43546
|
-
const label2 = `${type.toUpperCase()}
|
|
43549
|
+
const label2 = `${type.toUpperCase()}`;
|
|
43547
43550
|
console.log(source_default.bold(`
|
|
43548
43551
|
Updating agent instruction files (${label2})...
|
|
43549
43552
|
`));
|
|
@@ -43579,14 +43582,14 @@ Updating agent instruction files (${label2})...
|
|
|
43579
43582
|
message: "Select variant:",
|
|
43580
43583
|
choices: [
|
|
43581
43584
|
{
|
|
43582
|
-
title: "
|
|
43583
|
-
value: "
|
|
43584
|
-
description: "
|
|
43585
|
+
title: "Minimal (Recommended)",
|
|
43586
|
+
value: "instruction",
|
|
43587
|
+
description: "Just tells AI to call `knowns agents guideline` for rules"
|
|
43585
43588
|
},
|
|
43586
43589
|
{
|
|
43587
|
-
title: "
|
|
43588
|
-
value: "
|
|
43589
|
-
description: "
|
|
43590
|
+
title: "Full (Embedded)",
|
|
43591
|
+
value: "general",
|
|
43592
|
+
description: "Complete guidelines embedded in file"
|
|
43590
43593
|
}
|
|
43591
43594
|
],
|
|
43592
43595
|
initial: 0
|
|
@@ -43610,7 +43613,8 @@ Updating agent instruction files (${label2})...
|
|
|
43610
43613
|
console.log(source_default.yellow("\n\u26A0\uFE0F No files selected"));
|
|
43611
43614
|
return;
|
|
43612
43615
|
}
|
|
43613
|
-
const
|
|
43616
|
+
const variantLabel = variantResponse.variant === "instruction" ? " (minimal)" : " (full)";
|
|
43617
|
+
const label = `${typeResponse.type.toUpperCase()}${variantLabel}`;
|
|
43614
43618
|
const confirmResponse = await (0, import_prompts.default)({
|
|
43615
43619
|
type: "confirm",
|
|
43616
43620
|
name: "confirm",
|
|
@@ -43677,13 +43681,14 @@ async function updateFiles(files, guidelines) {
|
|
|
43677
43681
|
}
|
|
43678
43682
|
console.log();
|
|
43679
43683
|
}
|
|
43680
|
-
var syncCommand = new Command("sync").description("Sync/update all agent instruction files with latest guidelines").option("--type <type>", "Guidelines type: cli or mcp", "cli").option("--
|
|
43684
|
+
var syncCommand = new Command("sync").description("Sync/update all agent instruction files with latest guidelines").option("--type <type>", "Guidelines type: cli or mcp", "cli").option("--full", "Use full embedded guidelines (default: minimal instruction)").option("--all", "Update all instruction files (including Gemini, Copilot)").action(async (options2) => {
|
|
43681
43685
|
try {
|
|
43682
43686
|
const type = options2.type === "mcp" ? "mcp" : "cli";
|
|
43683
|
-
const variant = options2.
|
|
43687
|
+
const variant = options2.full ? "general" : "instruction";
|
|
43684
43688
|
const guidelines = getGuidelines(type, variant);
|
|
43685
43689
|
const filesToUpdate = options2.all ? INSTRUCTION_FILES : INSTRUCTION_FILES.filter((f) => f.selected);
|
|
43686
|
-
const
|
|
43690
|
+
const variantLabel = variant === "instruction" ? " (minimal)" : " (full)";
|
|
43691
|
+
const label = `${type.toUpperCase()}${variantLabel}`;
|
|
43687
43692
|
console.log(source_default.bold(`
|
|
43688
43693
|
Syncing agent instructions (${label})...
|
|
43689
43694
|
`));
|
|
@@ -43694,6 +43699,21 @@ Syncing agent instructions (${label})...
|
|
|
43694
43699
|
}
|
|
43695
43700
|
});
|
|
43696
43701
|
agentsCommand.addCommand(syncCommand);
|
|
43702
|
+
var guidelineCommand = new Command("guideline").description("Output guidelines for AI agents (use this at session start)").option("--cli", "Show CLI-specific guidelines").option("--mcp", "Show MCP-specific guidelines").action(async (options2) => {
|
|
43703
|
+
try {
|
|
43704
|
+
if (options2.cli) {
|
|
43705
|
+
console.log(general_default);
|
|
43706
|
+
} else if (options2.mcp) {
|
|
43707
|
+
console.log(general_default2);
|
|
43708
|
+
} else {
|
|
43709
|
+
console.log(unified_default);
|
|
43710
|
+
}
|
|
43711
|
+
} catch (error48) {
|
|
43712
|
+
console.error("Error:", error48 instanceof Error ? error48.message : String(error48));
|
|
43713
|
+
process.exit(1);
|
|
43714
|
+
}
|
|
43715
|
+
});
|
|
43716
|
+
agentsCommand.addCommand(guidelineCommand);
|
|
43697
43717
|
|
|
43698
43718
|
// src/commands/init.ts
|
|
43699
43719
|
function checkGitExists(projectRoot) {
|
|
@@ -70412,6 +70432,52 @@ async function handleSearchDocs(args2) {
|
|
|
70412
70432
|
});
|
|
70413
70433
|
}
|
|
70414
70434
|
|
|
70435
|
+
// src/mcp/handlers/guideline.ts
|
|
70436
|
+
var getGuidelineSchema = external_exports.object({
|
|
70437
|
+
type: external_exports.enum(["unified", "cli", "mcp"]).optional().default("unified")
|
|
70438
|
+
});
|
|
70439
|
+
function stripMarkers(content) {
|
|
70440
|
+
return content.replace(/<!-- KNOWNS GUIDELINES START -->\n?/g, "").replace(/<!-- KNOWNS GUIDELINES END -->\n?/g, "").trim();
|
|
70441
|
+
}
|
|
70442
|
+
var guidelineTools = [
|
|
70443
|
+
{
|
|
70444
|
+
name: "get_guideline",
|
|
70445
|
+
description: "Get usage guidelines for Knowns CLI/MCP. Call this at session start to understand how to use the tools correctly.",
|
|
70446
|
+
inputSchema: {
|
|
70447
|
+
type: "object",
|
|
70448
|
+
properties: {
|
|
70449
|
+
type: {
|
|
70450
|
+
type: "string",
|
|
70451
|
+
enum: ["unified", "cli", "mcp"],
|
|
70452
|
+
description: "Type of guidelines: unified (default, covers both), cli (CLI only), mcp (MCP only)"
|
|
70453
|
+
}
|
|
70454
|
+
}
|
|
70455
|
+
}
|
|
70456
|
+
}
|
|
70457
|
+
];
|
|
70458
|
+
async function handleGetGuideline(args2) {
|
|
70459
|
+
const input = getGuidelineSchema.parse(args2 || {});
|
|
70460
|
+
let guidelines;
|
|
70461
|
+
switch (input.type) {
|
|
70462
|
+
case "cli":
|
|
70463
|
+
guidelines = stripMarkers(general_default);
|
|
70464
|
+
break;
|
|
70465
|
+
case "mcp":
|
|
70466
|
+
guidelines = stripMarkers(general_default2);
|
|
70467
|
+
break;
|
|
70468
|
+
default:
|
|
70469
|
+
guidelines = unified_default;
|
|
70470
|
+
}
|
|
70471
|
+
return {
|
|
70472
|
+
content: [
|
|
70473
|
+
{
|
|
70474
|
+
type: "text",
|
|
70475
|
+
text: guidelines
|
|
70476
|
+
}
|
|
70477
|
+
]
|
|
70478
|
+
};
|
|
70479
|
+
}
|
|
70480
|
+
|
|
70415
70481
|
// src/mcp/server.ts
|
|
70416
70482
|
var fileStore = new FileStore(process.cwd());
|
|
70417
70483
|
var server = new Server(
|
|
@@ -70426,7 +70492,7 @@ var server = new Server(
|
|
|
70426
70492
|
}
|
|
70427
70493
|
}
|
|
70428
70494
|
);
|
|
70429
|
-
var tools = [...taskTools, ...timeTools, ...boardTools, ...docTools];
|
|
70495
|
+
var tools = [...taskTools, ...timeTools, ...boardTools, ...docTools, ...guidelineTools];
|
|
70430
70496
|
server.setRequestHandler(ListToolsRequestSchema, async () => {
|
|
70431
70497
|
return { tools };
|
|
70432
70498
|
});
|
|
@@ -70468,6 +70534,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
|
|
70468
70534
|
return await handleUpdateDoc(args2);
|
|
70469
70535
|
case "search_docs":
|
|
70470
70536
|
return await handleSearchDocs(args2);
|
|
70537
|
+
// Guideline handler
|
|
70538
|
+
case "get_guideline":
|
|
70539
|
+
return await handleGetGuideline(args2);
|
|
70471
70540
|
default:
|
|
70472
70541
|
return errorResponse(`Unknown tool: ${name}`);
|
|
70473
70542
|
}
|
|
@@ -70773,7 +70842,7 @@ async function notifyCliUpdate(options2) {
|
|
|
70773
70842
|
// package.json
|
|
70774
70843
|
var package_default = {
|
|
70775
70844
|
name: "knowns",
|
|
70776
|
-
version: "0.8.
|
|
70845
|
+
version: "0.8.2",
|
|
70777
70846
|
description: "CLI tool for dev teams to manage tasks and documentation",
|
|
70778
70847
|
module: "index.ts",
|
|
70779
70848
|
type: "module",
|
|
@@ -70784,7 +70853,6 @@ var package_default = {
|
|
|
70784
70853
|
main: "./dist/index.js",
|
|
70785
70854
|
files: [
|
|
70786
70855
|
"dist",
|
|
70787
|
-
"CLAUDE.md",
|
|
70788
70856
|
"README.md",
|
|
70789
70857
|
"CHANGELOG.md",
|
|
70790
70858
|
"LICENSE"
|
package/dist/mcp/server.js
CHANGED
|
@@ -33124,6 +33124,61 @@ async function handleSearchDocs(args) {
|
|
|
33124
33124
|
});
|
|
33125
33125
|
}
|
|
33126
33126
|
|
|
33127
|
+
// src/templates/cli/general.md
|
|
33128
|
+
var general_default = '<!-- KNOWNS GUIDELINES START -->\n# Knowns CLI Guidelines\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n## Core Rules\n\n| Rule | Description |\n|------|-------------|\n| **CLI Only** | Use CLI commands for ALL operations. NEVER edit .md files directly |\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Always `time start` when taking task, `time stop` when done |\n| **--plain Flag** | Use `--plain` ONLY for view/list/search commands (NOT create/edit) |\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## Workflow\n\n### Session Start\n```bash\nknowns doc list --plain\nknowns doc "README" --plain\nknowns doc "ARCHITECTURE" --plain\nknowns doc "CONVENTIONS" --plain\n```\n\n### Task Lifecycle\n\n**1. Create & Take**\n```bash\nknowns task create "Title" -d "Description" --priority high -l "label1,label2"\nknowns task edit <id> -s in-progress -a @me\nknowns time start <id>\n```\n\n**2. Research**\n```bash\nknowns task <id> --plain # Follow ALL refs\nknowns search "keyword" --type doc --plain\nknowns doc "path/name" --plain\nknowns search "keyword" --type task --status done --plain\n```\n\n**3. Plan \u2192 Wait approval**\n```bash\nknowns task edit <id> --plan $\'1. Step (see @doc/xxx)\\n2. Step\'\n```\n\n**4. Implement**\n```bash\nknowns task edit <id> --append-notes "\u2713 Completed: feature X"\n```\n\n**5. Complete**\n```bash\nknowns time stop\nknowns task edit <id> -s done\n```\n\n---\n\n## Commands Quick Reference\n\n### Tasks\n```bash\nknowns task create "Title" -d "Desc" --priority high -l "labels" --parent <id>\nknowns task <id> --plain\nknowns task edit <id> -s <status> -a @me\nknowns task edit <id> --plan "..." --notes "..." --append-notes "..."\nknowns task edit <id> --check-ac 1 --check-ac 2\nknowns task list --plain\nknowns task list --status in-progress --plain\nknowns search "query" --type task --plain\n```\n\n### Time\n```bash\nknowns time start <id>\nknowns time stop\nknowns time add <id> 2h -n "Note"\nknowns time status\nknowns time report --from "2025-01-01" --to "2025-12-31"\n```\n\n### Docs\n```bash\nknowns doc list --plain\nknowns doc "path/name" --plain\nknowns doc create "Title" -d "Desc" -t "tags" -f "folder"\nknowns doc edit "name" -c "content"\nknowns doc edit "name" -a "append content"\nknowns search "query" --type doc --plain\n```\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**Subtasks:** Use raw ID \u2014 `--parent 48` not `--parent task-48`\n\n---\n\n## Status & Priority\n\n| Status | When |\n|--------|------|\n| `todo` | Not started |\n| `in-progress` | Working |\n| `in-review` | PR submitted |\n| `blocked` | Waiting |\n| `done` | Complete |\n\n| Priority | Level |\n|----------|-------|\n| `low` | Nice-to-have |\n| `medium` | Normal |\n| `high` | Urgent |\n\n---\n\n## Task Quality\n\n**Title**: Clear action\n\u274C "Fix bug" \u2192 \u2705 "Fix login timeout on slow networks"\n\n**Description**: WHY + WHAT, link docs with `@doc/path`\n\n**Acceptance**: Outcomes, not implementation\n\u274C "Add handleLogin()" \u2192 \u2705 "User can login and receive token"\n\n---\n\n## Common Mistakes\n\n| \u274C Wrong | \u2705 Right |\n|----------|----------|\n| Edit .md directly | Use CLI commands |\n| Skip timer | Always start/stop |\n| Code before docs | Read docs first |\n| Code before approval | Wait for approval |\n| `--parent task-48` | `--parent 48` |\n| Ignore refs | Follow ALL refs |\n| `--plain` with create/edit | `--plain` only for view/list/search |\n\n---\n\n## Definition of Done\n\n- [ ] Work completed\n- [ ] Notes added\n- [ ] Timer stopped\n- [ ] Tests passing\n- [ ] Docs updated\n- [ ] Status: done\n<!-- KNOWNS GUIDELINES END -->\n';
|
|
33129
|
+
|
|
33130
|
+
// src/templates/mcp/general.md
|
|
33131
|
+
var general_default2 = '<!-- KNOWNS GUIDELINES START -->\n# Knowns MCP Guidelines\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n## Core Rules\n\n| Rule | Description |\n|------|-------------|\n| **MCP Only** | Use MCP tools for ALL operations. NEVER edit .md files directly |\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Always `start_time` when taking task, `stop_time` when done |\n| **Fallback to CLI** | If an MCP tool is missing, run the equivalent CLI command instead |\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## Workflow\n\n### Session Start\n```\nlist_docs({})\nget_doc({ path: "README" })\nget_doc({ path: "ARCHITECTURE" })\nget_doc({ path: "CONVENTIONS" })\n```\n\n### Task Lifecycle\n\n**1. Create & Take**\n```\ncreate_task({ title, description, priority, labels })\nupdate_task({ taskId, status: "in-progress", assignee: "@username" })\nstart_time({ taskId })\n```\n\n**2. Research**\n```\nget_task({ taskId }) # Follow ALL refs\nsearch_docs({ query })\nget_doc({ path })\nsearch_tasks({ query, status: "done" })\n```\n\n**3. Plan \u2192 Wait approval**\n```\nupdate_task({ taskId, plan: "1. Step (see @doc/xxx)\\n2. Step" })\n```\n\n**4. Implement**\n```\nupdate_task({ taskId, appendNotes: "\u2713 Completed: feature X" })\n```\n\n**5. Complete**\n```\nstop_time({ taskId })\nupdate_task({ taskId, status: "done" })\n```\n\n---\n\n## Tools Quick Reference\n\n### Tasks\n- `create_task({ title, description, priority?, labels?, parent? })`\n- `get_task({ taskId })`\n- `update_task({ taskId, status?, plan?, notes?, appendNotes? })`\n- `list_tasks({ status?, assignee?, label? })`\n- `search_tasks({ query, status? })`\n\n### Time\n- `start_time({ taskId })`\n- `stop_time({ taskId })`\n- `add_time({ taskId, duration, note? })` \u2014 duration: "2h", "30m"\n- `get_time_report({ from?, to?, groupBy? })`\n\n### Docs\n- `list_docs({ tag? })`\n- `get_doc({ path })` \u2014 path without .md\n- `create_doc({ title, description, tags?, folder?, content? })`\n- `update_doc({ path, content?, appendContent? })`\n- `search_docs({ query, tag? })`\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**Subtasks:** Use raw ID \u2014 `parent: "48"` not `parent: "task-48"`\n\n---\n\n## Status & Priority\n\n| Status | When |\n|--------|------|\n| `todo` | Not started |\n| `in-progress` | Working |\n| `in-review` | PR submitted |\n| `blocked` | Waiting |\n| `done` | Complete |\n\n| Priority | Level |\n|----------|-------|\n| `low` | Nice-to-have |\n| `medium` | Normal |\n| `high` | Urgent |\n\n---\n\n## Task Quality\n\n**Title**: Clear action\n\u274C "Fix bug" \u2192 \u2705 "Fix login timeout on slow networks"\n\n**Description**: WHY + WHAT, link docs with `@doc/path`\n\n**Acceptance**: Outcomes, not implementation\n\u274C "Add handleLogin()" \u2192 \u2705 "User can login and receive token"\n\n---\n\n## Common Mistakes\n\n| \u274C Wrong | \u2705 Right |\n|----------|----------|\n| Edit .md directly | Use MCP tools |\n| Skip timer | Always start/stop |\n| Code before docs | Read docs first |\n| Code before approval | Wait for approval |\n| `parent: "task-48"` | `parent: "48"` |\n| Ignore refs | Follow ALL refs |\n\n---\n\n## Definition of Done\n\n- [ ] Work completed\n- [ ] Notes added\n- [ ] Timer stopped\n- [ ] Tests passing\n- [ ] Docs updated\n- [ ] Status: done\n<!-- KNOWNS GUIDELINES END -->\n';
|
|
33132
|
+
|
|
33133
|
+
// src/templates/unified.md
|
|
33134
|
+
var unified_default = '# Knowns Guidelines\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n## Core Rules\n\n| Rule | Description |\n|------|-------------|\n| **Never Edit .md** | Use CLI commands or MCP tools. 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| **MCP \u2192 CLI Fallback** | If an MCP tool is missing, run the equivalent CLI command instead |\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> - Title.md` | `@.knowns/docs/<path>.md` |\n\nWhen reading refs in output, extract ID/path and call appropriate tool. Follow refs recursively.\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`, `a7f3k9` | Current (6-char base36) |\n\n**Subtasks:** Use raw ID for parent (NOT "task-48")\n\n---\n\n## Workflow\n\n### Session Start\n1. List docs \u2192 Read README, ARCHITECTURE, CONVENTIONS\n2. Review task backlog\n\n### Task Lifecycle\n1. **Take**: Set status `in-progress`, assign, start timer\n2. **Research**: Get task details, follow ALL refs, search related docs\n3. **Plan**: Create plan with doc refs \u2192 Wait for approval\n4. **Implement**: Work step by step, append progress notes\n5. **Complete**: Stop timer, set status `done`\n\n### Post-Completion Changes\nReopen (in-progress) \u2192 Start timer \u2192 Document reason \u2192 Implement \u2192 Complete\n\n---\n\n## Command Reference\n\n### Task Commands\n| Action | CLI | MCP |\n|--------|-----|-----|\n| Create | `knowns task create "T" -d "D" --priority high` | `create_task({ title, description, priority })` |\n| Create Subtask | `knowns task create "T" --parent 48` | `create_task({ title, parent: "48" })` |\n| View | `knowns task <id> --plain` | `get_task({ taskId })` |\n| List | `knowns task list --plain` | `list_tasks({})` |\n| Update | `knowns task edit <id> -s done` | `update_task({ taskId, status: "done" })` |\n| Search | `knowns search "q" --type task --plain` | `search_tasks({ query })` |\n\n### Doc Commands\n| Action | CLI | MCP |\n|--------|-----|-----|\n| List | `knowns doc list --plain` | `list_docs({})` |\n| View | `knowns doc "path" --plain` | `get_doc({ path })` |\n| Create | `knowns doc create "T" -d "D" -f "folder"` | `create_doc({ title, description, folder })` |\n| Update | `knowns doc edit "name" -a "content"` | `update_doc({ path, appendContent })` |\n| Search | `knowns search "q" --type doc --plain` | `search_docs({ query })` |\n\n### Time Commands\n| Action | CLI | MCP |\n|--------|-----|-----|\n| Start | `knowns time start <id>` | `start_time({ taskId })` |\n| Stop | `knowns time stop` | `stop_time({ taskId })` |\n| Add | `knowns time add <id> 2h -n "Note"` | `add_time({ taskId, duration, note })` |\n\n---\n\n## Status & Priority\n\n| Status | Use 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 | Description |\n|----------|-------------|\n| `low` | Nice-to-have |\n| `medium` | Normal (default) |\n| `high` | Urgent |\n\n---\n\n## CLI Notes\n\n- Use `--plain` flag ONLY for view/list/search commands (NOT create/edit)\n- Multi-line: `$\'line1\\nline2\'` (bash) or heredoc\n\n---\n\n## Common Mistakes\n\n| \u274C Wrong | \u2705 Right |\n|----------|----------|\n| Edit .md files directly | Use CLI/MCP tools |\n| Skip time tracking | Always start/stop timer |\n| Code before reading docs | Read ALL related docs first |\n| Code before plan approval | Wait for user approval |\n| `--parent task-48` | `--parent 48` (raw ID only) |\n| Ignore refs in task | Follow ALL refs recursively |\n| `--plain` with create/edit | `--plain` only for view/list/search |\n\n---\n\n## Definition of Done\n\n- [ ] All work completed and verified\n- [ ] Implementation notes added\n- [ ] Timer stopped\n- [ ] Tests passing\n- [ ] Documentation updated\n- [ ] Status set to done\n';
|
|
33135
|
+
|
|
33136
|
+
// src/mcp/handlers/guideline.ts
|
|
33137
|
+
var getGuidelineSchema = external_exports3.object({
|
|
33138
|
+
type: external_exports3.enum(["unified", "cli", "mcp"]).optional().default("unified")
|
|
33139
|
+
});
|
|
33140
|
+
function stripMarkers(content) {
|
|
33141
|
+
return content.replace(/<!-- KNOWNS GUIDELINES START -->\n?/g, "").replace(/<!-- KNOWNS GUIDELINES END -->\n?/g, "").trim();
|
|
33142
|
+
}
|
|
33143
|
+
var guidelineTools = [
|
|
33144
|
+
{
|
|
33145
|
+
name: "get_guideline",
|
|
33146
|
+
description: "Get usage guidelines for Knowns CLI/MCP. Call this at session start to understand how to use the tools correctly.",
|
|
33147
|
+
inputSchema: {
|
|
33148
|
+
type: "object",
|
|
33149
|
+
properties: {
|
|
33150
|
+
type: {
|
|
33151
|
+
type: "string",
|
|
33152
|
+
enum: ["unified", "cli", "mcp"],
|
|
33153
|
+
description: "Type of guidelines: unified (default, covers both), cli (CLI only), mcp (MCP only)"
|
|
33154
|
+
}
|
|
33155
|
+
}
|
|
33156
|
+
}
|
|
33157
|
+
}
|
|
33158
|
+
];
|
|
33159
|
+
async function handleGetGuideline(args) {
|
|
33160
|
+
const input = getGuidelineSchema.parse(args || {});
|
|
33161
|
+
let guidelines;
|
|
33162
|
+
switch (input.type) {
|
|
33163
|
+
case "cli":
|
|
33164
|
+
guidelines = stripMarkers(general_default);
|
|
33165
|
+
break;
|
|
33166
|
+
case "mcp":
|
|
33167
|
+
guidelines = stripMarkers(general_default2);
|
|
33168
|
+
break;
|
|
33169
|
+
default:
|
|
33170
|
+
guidelines = unified_default;
|
|
33171
|
+
}
|
|
33172
|
+
return {
|
|
33173
|
+
content: [
|
|
33174
|
+
{
|
|
33175
|
+
type: "text",
|
|
33176
|
+
text: guidelines
|
|
33177
|
+
}
|
|
33178
|
+
]
|
|
33179
|
+
};
|
|
33180
|
+
}
|
|
33181
|
+
|
|
33127
33182
|
// src/mcp/server.ts
|
|
33128
33183
|
var fileStore = new FileStore(process.cwd());
|
|
33129
33184
|
var server = new Server(
|
|
@@ -33138,7 +33193,7 @@ var server = new Server(
|
|
|
33138
33193
|
}
|
|
33139
33194
|
}
|
|
33140
33195
|
);
|
|
33141
|
-
var tools = [...taskTools, ...timeTools, ...boardTools, ...docTools];
|
|
33196
|
+
var tools = [...taskTools, ...timeTools, ...boardTools, ...docTools, ...guidelineTools];
|
|
33142
33197
|
server.setRequestHandler(ListToolsRequestSchema, async () => {
|
|
33143
33198
|
return { tools };
|
|
33144
33199
|
});
|
|
@@ -33180,6 +33235,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
|
|
33180
33235
|
return await handleUpdateDoc(args);
|
|
33181
33236
|
case "search_docs":
|
|
33182
33237
|
return await handleSearchDocs(args);
|
|
33238
|
+
// Guideline handler
|
|
33239
|
+
case "get_guideline":
|
|
33240
|
+
return await handleGetGuideline(args);
|
|
33183
33241
|
default:
|
|
33184
33242
|
return errorResponse(`Unknown tool: ${name}`);
|
|
33185
33243
|
}
|