knowns 0.8.4 → 0.8.6
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/dist/index.js +30 -28
- package/dist/mcp/server.js +16 -8
- package/dist/ui/assets/index-VYsw6Uus.js +317 -0
- package/dist/ui/index.html +1 -1
- package/package.json +4 -22
- package/dist/ui/assets/index-NuqnrMx0.js +0 -313
package/dist/index.js
CHANGED
|
@@ -43479,19 +43479,22 @@ var import_prompts = __toESM(require_prompts3(), 1);
|
|
|
43479
43479
|
var core_rules_default = '# Core Rules\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n---\n\n## \u{1F3AF} The Golden Rule\n\n**If you want to change ANYTHING in a task or doc, use CLI commands or MCP tools. NEVER edit .md files directly.**\n\nWhy? Direct file editing breaks metadata synchronization, Git tracking, and relationships.\n\n---\n\n## \u26A0\uFE0F CRITICAL: The -a Flag Confusion\n\nThe `-a` flag means DIFFERENT things in different commands:\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `task edit` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `doc edit` | `--append` (append content) | ~~assignee~~ |\n\n### Acceptance Criteria: Use --ac\n\n```bash\n# \u274C WRONG: -a is assignee, NOT acceptance criteria!\nknowns task edit 35 -a "- [ ] Criterion" # Sets assignee to garbage!\nknowns task create "Title" -a "Criterion" # Sets assignee to garbage!\n\n# \u2705 CORRECT: Use --ac for acceptance criteria\nknowns task edit 35 --ac "Criterion one"\nknowns task edit 35 --ac "Criterion two"\nknowns task create "Title" --ac "Criterion one" --ac "Criterion two"\n```\n\n---\n\n## Core Principles\n\n| Rule | Description |\n|------|-------------|\n| **CLI/MCP Only** | Use commands for ALL operations. NEVER edit .md files directly |\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Always start timer when taking task, stop when done |\n| **Plan Approval** | Share plan with user, WAIT for approval before coding |\n| **Check AC After Work** | Only mark acceptance criteria done AFTER completing the work |\n\n---\n\n## The --plain Flag\n\n**ONLY for view/list/search commands (NOT create/edit):**\n\n```bash\n# \u2705 CORRECT\nknowns task <id> --plain\nknowns task list --plain\nknowns doc "path" --plain\nknowns doc list --plain\nknowns search "query" --plain\n\n# \u274C WRONG (create/edit don\'t support --plain)\nknowns task create "Title" --plain # ERROR!\nknowns task edit <id> -s done --plain # ERROR!\nknowns doc create "Title" --plain # ERROR!\nknowns doc edit "name" -c "..." --plain # ERROR!\n```\n\n---\n\n## Reference System\n\n| Context | Task Format | Doc Format |\n|---------|-------------|------------|\n| **Writing** (input) | `@task-<id>` | `@doc/<path>` |\n| **Reading** (output) | `@.knowns/tasks/task-<id>` | `@.knowns/docs/<path>.md` |\n\nFollow refs recursively until complete context gathered.\n\n---\n\n## Task IDs\n\n| Format | Example | Notes |\n|--------|---------|-------|\n| Sequential | `48`, `49` | Legacy numeric |\n| Hierarchical | `48.1`, `48.2` | Legacy subtasks |\n| Random | `qkh5ne` | Current (6-char) |\n\n**CRITICAL:** Use raw ID for `--parent`:\n```bash\n# \u2705 CORRECT\nknowns task create "Title" --parent 48\n\n# \u274C WRONG\nknowns task create "Title" --parent task-48\n```\n\n---\n\n## Status & Priority\n\n| Status | When |\n|--------|------|\n| `todo` | Not started (default) |\n| `in-progress` | Currently working |\n| `in-review` | PR submitted |\n| `blocked` | Waiting on dependency |\n| `done` | All criteria met |\n\n| Priority | Level |\n|----------|-------|\n| `low` | Nice-to-have |\n| `medium` | Normal (default) |\n| `high` | Urgent |\n';
|
|
43480
43480
|
|
|
43481
43481
|
// src/templates/guidelines/commands-reference.md
|
|
43482
|
-
var commands_reference_default = '#
|
|
43482
|
+
var commands_reference_default = '# Commands Reference\n\n## task create\n\n```bash\nknowns task create <title> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--description` | `-d` | Task description |\n| `--ac` | | Acceptance criterion (repeatable) |\n| `--labels` | `-l` | Comma-separated labels |\n| `--assignee` | `-a` | Assign to user \u26A0\uFE0F |\n| `--priority` | | low/medium/high |\n| `--status` | `-s` | Initial status |\n| `--parent` | | Parent task ID (raw ID only!) |\n\n**\u26A0\uFE0F `-a` = assignee, NOT acceptance criteria! Use `--ac` for AC.**\n\n---\n\n## task edit\n\n```bash\nknowns task edit <id> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--title` | `-t` | Change title |\n| `--description` | `-d` | Change description |\n| `--status` | `-s` | Change status |\n| `--priority` | | Change priority |\n| `--labels` | `-l` | Set labels |\n| `--assignee` | `-a` | Assign user \u26A0\uFE0F |\n| `--parent` | | Move to parent |\n| `--ac` | | Add acceptance criterion |\n| `--check-ac` | | Mark AC done (1-indexed) |\n| `--uncheck-ac` | | Unmark AC (1-indexed) |\n| `--remove-ac` | | Delete AC (1-indexed) |\n| `--plan` | | Set implementation plan |\n| `--notes` | | Replace notes |\n| `--append-notes` | | Add to notes |\n\n**\u26A0\uFE0F `-a` = assignee, NOT acceptance criteria! Use `--ac` for AC.**\n\n---\n\n## task view/list\n\n```bash\nknowns task <id> --plain # View single task\nknowns task list --plain # List all\nknowns task list --status in-progress --plain\nknowns task list --assignee @me --plain\nknowns task list --tree --plain # Tree hierarchy\n```\n\n---\n\n## doc create\n\n```bash\nknowns doc create <title> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--description` | `-d` | Description |\n| `--tags` | `-t` | Comma-separated tags |\n| `--folder` | `-f` | Folder path |\n\n---\n\n## doc edit\n\n```bash\nknowns doc edit <name> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--title` | `-t` | Change title |\n| `--description` | `-d` | Change description |\n| `--tags` | | Set tags |\n| `--content` | `-c` | Replace content |\n| `--append` | `-a` | Append content \u26A0\uFE0F |\n| `--content-file` | | Content from file |\n| `--append-file` | | Append from file |\n\n**\u26A0\uFE0F In doc edit, `-a` = append content, NOT assignee!**\n\n---\n\n## doc view/list\n\n```bash\nknowns doc <path> --plain # View single doc\nknowns doc list --plain # List all\nknowns doc list --tag api --plain # Filter by tag\n```\n\n---\n\n## time\n\n```bash\nknowns time start <id> # REQUIRED when taking task\nknowns time stop # REQUIRED when completing\nknowns time pause\nknowns time resume\nknowns time status\nknowns time add <id> <duration> -n "Note" -d "2025-01-01"\n```\n\n---\n\n## search\n\n```bash\nknowns search "query" --plain\nknowns search "auth" --type task --plain\nknowns search "api" --type doc --plain\nknowns search "bug" --type task --status in-progress --priority high --plain\n```\n\n---\n\n## Multi-line Input (Bash/Zsh)\n\n```bash\nknowns task edit <id> --plan $\'1. Step\\n2. Step\\n3. Step\'\n```\n';
|
|
43483
43483
|
|
|
43484
43484
|
// src/templates/guidelines/workflow-completion.md
|
|
43485
|
-
var workflow_completion_default = '# Task Completion
|
|
43485
|
+
var workflow_completion_default = '# Task Completion\n\n## Definition of Done\n\nA task is **Done** when ALL of these are complete:\n\n| Requirement | Command |\n|-------------|---------|\n| All AC checked | `knowns task edit <id> --check-ac N` |\n| Notes added | `knowns task edit <id> --notes "Summary"` |\n| Timer stopped | `knowns time stop` |\n| Status = done | `knowns task edit <id> -s done` |\n| Tests pass | Run test suite |\n\n---\n\n## Completion Steps\n\n```bash\n# 1. Verify all AC are checked\nknowns task <id> --plain\n\n# 2. Add implementation notes\nknowns task edit <id> --notes $\'## Summary\nWhat was done and key decisions.\'\n\n# 3. Stop timer (REQUIRED!)\nknowns time stop\n\n# 4. Mark done\nknowns task edit <id> -s done\n```\n\n---\n\n## Post-Completion Changes\n\nIf user requests changes after task is done:\n\n```bash\nknowns task edit <id> -s in-progress # Reopen\nknowns time start <id> # Restart timer\nknowns task edit <id> --ac "Fix: description"\nknowns task edit <id> --append-notes "\u{1F504} Reopened: reason"\n# Complete work, then follow completion steps again\n```\n\n---\n\n## Checklist\n\n- [ ] All AC checked (`--check-ac`)\n- [ ] Notes added (`--notes`)\n- [ ] Timer stopped (`time stop`)\n- [ ] Tests pass\n- [ ] Status = done (`-s done`)\n';
|
|
43486
43486
|
|
|
43487
43487
|
// src/templates/guidelines/workflow-creation.md
|
|
43488
|
-
var workflow_creation_default = '# Task Creation
|
|
43488
|
+
var workflow_creation_default = '# Task Creation\n\n## Before Creating\n\n```bash\n# Search for existing tasks first\nknowns search "keyword" --type task --plain\n```\n\n---\n\n## Create Task\n\n```bash\nknowns task create "Clear title (WHAT)" \\\n -d "Description (WHY)" \\\n --ac "Outcome 1" \\\n --ac "Outcome 2" \\\n --priority medium \\\n -l "labels"\n```\n\n---\n\n## Quality Guidelines\n\n### Title\n| \u274C Bad | \u2705 Good |\n|--------|---------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout |\n\n### Description\nExplain WHY. Include doc refs: `@doc/security-patterns`\n\n### Acceptance Criteria\n**Outcome-focused, NOT implementation steps:**\n\n| \u274C Bad | \u2705 Good |\n|--------|---------|\n| Add handleLogin() function | User can login |\n| Use bcrypt | Passwords are hashed |\n| Add try-catch | Errors return proper HTTP codes |\n\n---\n\n## Subtasks\n\n```bash\nknowns task create "Parent task"\nknowns task create "Subtask" --parent 48 # Raw ID only!\n```\n\n---\n\n## Anti-Patterns\n\n- \u274C Too many AC in one task \u2192 Split into multiple tasks\n- \u274C Implementation steps as AC \u2192 Write outcomes instead\n- \u274C Skip search \u2192 Always check existing tasks first\n';
|
|
43489
43489
|
|
|
43490
43490
|
// src/templates/guidelines/workflow-execution.md
|
|
43491
|
-
var workflow_execution_default = '# Task Execution
|
|
43491
|
+
var workflow_execution_default = '# Task Execution\n\n## Step 1: Take Task\n\n```bash\nknowns task edit <id> -s in-progress -a @me\nknowns time start <id> # REQUIRED!\n```\n\n---\n\n## Step 2: Research\n\n```bash\n# Read task and follow ALL refs\nknowns task <id> --plain\n# @.knowns/docs/xxx.md \u2192 knowns doc "xxx" --plain\n# @.knowns/tasks/task-YY \u2192 knowns task YY --plain\n\n# Search related docs\nknowns search "keyword" --type doc --plain\n\n# Check similar done tasks\nknowns search "keyword" --type task --status done --plain\n```\n\n---\n\n## Step 3: Plan (BEFORE coding!)\n\n```bash\nknowns task edit <id> --plan $\'1. Research (see @doc/xxx)\n2. Implement\n3. Test\n4. Document\'\n```\n\n**\u26A0\uFE0F Share plan with user. WAIT for approval before coding.**\n\n---\n\n## Step 4: Implement\n\n```bash\n# Check AC only AFTER work is done\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "\u2713 Done: feature X"\n```\n\n---\n\n## Scope Changes\n\nIf new requirements emerge during work:\n\n```bash\n# Small: Add to current task\nknowns task edit <id> --ac "New requirement"\nknowns task edit <id> --append-notes "\u26A0\uFE0F Scope updated: reason"\n\n# Large: Ask user first, then create follow-up\nknowns task create "Follow-up: feature" -d "From task <id>"\n```\n\n**\u26A0\uFE0F Don\'t silently expand scope. Ask user first.**\n\n---\n\n## Key Rules\n\n1. **Plan before code** - Capture approach first\n2. **Wait for approval** - Don\'t start without OK\n3. **Check AC after work** - Not before\n4. **Ask on scope changes** - Don\'t expand silently\n';
|
|
43492
43492
|
|
|
43493
43493
|
// src/templates/guidelines/common-mistakes.md
|
|
43494
|
-
var common_mistakes_default = '# Common Mistakes\n\
|
|
43494
|
+
var common_mistakes_default = '# Common Mistakes\n\n## \u26A0\uFE0F CRITICAL: The -a Flag\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create/edit` | `--assignee` | ~~acceptance criteria~~ |\n| `doc edit` | `--append` | ~~assignee~~ |\n\n```bash\n# \u274C WRONG (sets assignee to garbage!)\nknowns task edit 35 -a "Criterion text"\n\n# \u2705 CORRECT (use --ac)\nknowns task edit 35 --ac "Criterion text"\n```\n\n---\n\n## Quick Reference\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| Edit .md files directly | Use CLI commands |\n| `-a "criterion"` | `--ac "criterion"` |\n| `--parent task-48` | `--parent 48` (raw ID) |\n| `--plain` with create/edit | `--plain` only for view/list |\n| Check AC before work done | Check AC AFTER work done |\n| Code before plan approval | Wait for user approval |\n| Code before reading docs | Read docs FIRST |\n| Skip time tracking | Always `time start`/`stop` |\n| Ignore task refs | Follow ALL `@.knowns/...` refs |\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\n| Set assignee to AC text | `knowns task edit <id> -a @me` |\n| Forgot to stop timer | `knowns time add <id> <duration>` |\n| Checked AC too early | `knowns task edit <id> --uncheck-ac N` |\n| Task not found | `knowns task list --plain` |\n';
|
|
43495
|
+
|
|
43496
|
+
// src/templates/guidelines/context-optimization.md
|
|
43497
|
+
var context_optimization_default = '# Context Optimization\n\nOptimize your context usage to work more efficiently within token limits.\n\n---\n\n## Output Format\n\n```bash\n# \u274C Verbose output\nknowns task 42 --json\n\n# \u2705 Compact output (always use --plain)\nknowns task 42 --plain\n```\n\n---\n\n## Search Before Read\n\n```bash\n# \u274C Reading all docs to find info\nknowns doc "doc1" --plain\nknowns doc "doc2" --plain\nknowns doc "doc3" --plain\n\n# \u2705 Search first, then read only relevant docs\nknowns search "authentication" --type doc --plain\nknowns doc "security-patterns" --plain # Only the relevant one\n```\n\n---\n\n## Selective File Reading\n\n```bash\n# \u274C Reading entire large file\nRead file (2000+ lines)\n\n# \u2705 Read specific sections\nRead file with offset=100 limit=50\n```\n\n---\n\n## Compact Notes\n\n```bash\n# \u274C Verbose notes\nknowns task edit 42 --append-notes "I have successfully completed the implementation of the authentication middleware which validates JWT tokens and handles refresh logic..."\n\n# \u2705 Compact notes\nknowns task edit 42 --append-notes "\u2713 Auth middleware + JWT validation done"\n```\n\n---\n\n## Avoid Redundant Operations\n\n| Don\'t | Do Instead |\n|-------|------------|\n| Re-read files already in context | Reference from memory |\n| List tasks/docs multiple times | List once, remember results |\n| Quote entire file contents | Summarize key points |\n| Repeat full error messages | Reference error briefly |\n\n---\n\n## Efficient Workflow\n\n| Phase | Context-Efficient Approach |\n|-------|---------------------------|\n| **Research** | Search \u2192 Read only matches |\n| **Planning** | Brief plan, not detailed prose |\n| **Coding** | Read only files being modified |\n| **Notes** | Bullet points, not paragraphs |\n| **Completion** | Summary, not full log |\n\n---\n\n## Quick Rules\n\n1. **Always `--plain`** - Never use `--json` unless specifically needed\n2. **Search first** - Don\'t read all docs hoping to find info\n3. **Read selectively** - Use offset/limit for large files\n4. **Write concise** - Compact notes, not essays\n5. **Don\'t repeat** - Reference context already loaded\n6. **Summarize** - Key points, not full quotes\n';
|
|
43495
43498
|
|
|
43496
43499
|
// src/templates/guidelines/index.ts
|
|
43497
43500
|
var CORE_RULES = core_rules_default.trim();
|
|
@@ -43500,6 +43503,7 @@ var WORKFLOW_CREATION = workflow_creation_default.trim();
|
|
|
43500
43503
|
var WORKFLOW_EXECUTION = workflow_execution_default.trim();
|
|
43501
43504
|
var WORKFLOW_COMPLETION = workflow_completion_default.trim();
|
|
43502
43505
|
var COMMON_MISTAKES = common_mistakes_default.trim();
|
|
43506
|
+
var CONTEXT_OPTIMIZATION = context_optimization_default.trim();
|
|
43503
43507
|
var Guidelines = {
|
|
43504
43508
|
// Core rules - always needed
|
|
43505
43509
|
core: CORE_RULES,
|
|
@@ -43513,6 +43517,8 @@ var Guidelines = {
|
|
|
43513
43517
|
},
|
|
43514
43518
|
// Common mistakes
|
|
43515
43519
|
mistakes: COMMON_MISTAKES,
|
|
43520
|
+
// Context optimization
|
|
43521
|
+
contextOptimization: CONTEXT_OPTIMIZATION,
|
|
43516
43522
|
/**
|
|
43517
43523
|
* Get full guidelines (all sections combined)
|
|
43518
43524
|
*/
|
|
@@ -43520,6 +43526,8 @@ var Guidelines = {
|
|
|
43520
43526
|
const content = [
|
|
43521
43527
|
CORE_RULES,
|
|
43522
43528
|
"---",
|
|
43529
|
+
CONTEXT_OPTIMIZATION,
|
|
43530
|
+
"---",
|
|
43523
43531
|
COMMANDS_REFERENCE,
|
|
43524
43532
|
"---",
|
|
43525
43533
|
WORKFLOW_CREATION,
|
|
@@ -43538,16 +43546,16 @@ ${content}
|
|
|
43538
43546
|
return content;
|
|
43539
43547
|
},
|
|
43540
43548
|
/**
|
|
43541
|
-
* Get compact guidelines (core + mistakes only)
|
|
43549
|
+
* Get compact guidelines (core + context optimization + mistakes only)
|
|
43542
43550
|
*/
|
|
43543
43551
|
getCompact() {
|
|
43544
|
-
return [CORE_RULES, "---", COMMON_MISTAKES].join("\n\n");
|
|
43552
|
+
return [CORE_RULES, "---", CONTEXT_OPTIMIZATION, "---", COMMON_MISTAKES].join("\n\n");
|
|
43545
43553
|
},
|
|
43546
43554
|
/**
|
|
43547
43555
|
* Get guidelines for specific workflow stage
|
|
43548
43556
|
*/
|
|
43549
43557
|
getForStage(stage) {
|
|
43550
|
-
const sections = [CORE_RULES, "---"];
|
|
43558
|
+
const sections = [CORE_RULES, "---", CONTEXT_OPTIMIZATION, "---"];
|
|
43551
43559
|
switch (stage) {
|
|
43552
43560
|
case "creation":
|
|
43553
43561
|
sections.push(WORKFLOW_CREATION);
|
|
@@ -43592,11 +43600,11 @@ var INSTRUCTION_FILES = [
|
|
|
43592
43600
|
{ path: "GEMINI.md", name: "Gemini", selected: false },
|
|
43593
43601
|
{ path: ".github/copilot-instructions.md", name: "GitHub Copilot", selected: false }
|
|
43594
43602
|
];
|
|
43595
|
-
function getGuidelines(type, variant = "
|
|
43596
|
-
if (variant === "
|
|
43597
|
-
return
|
|
43603
|
+
function getGuidelines(type, variant = "general") {
|
|
43604
|
+
if (variant === "instruction") {
|
|
43605
|
+
return type === "mcp" ? MCP_INSTRUCTION : CLI_INSTRUCTION;
|
|
43598
43606
|
}
|
|
43599
|
-
return
|
|
43607
|
+
return Guidelines.getFull(true);
|
|
43600
43608
|
}
|
|
43601
43609
|
async function updateInstructionFile(filePath, guidelines) {
|
|
43602
43610
|
const fullPath = join3(PROJECT_ROOT, filePath);
|
|
@@ -43676,14 +43684,14 @@ Updating agent instruction files (${label2})...
|
|
|
43676
43684
|
message: "Select variant:",
|
|
43677
43685
|
choices: [
|
|
43678
43686
|
{
|
|
43679
|
-
title: "
|
|
43680
|
-
value: "instruction",
|
|
43681
|
-
description: "Just tells AI to call `knowns agents guideline` for rules"
|
|
43682
|
-
},
|
|
43683
|
-
{
|
|
43684
|
-
title: "Full (Embedded)",
|
|
43687
|
+
title: "Full (Recommended)",
|
|
43685
43688
|
value: "general",
|
|
43686
43689
|
description: "Complete guidelines embedded in file"
|
|
43690
|
+
},
|
|
43691
|
+
{
|
|
43692
|
+
title: "Minimal",
|
|
43693
|
+
value: "instruction",
|
|
43694
|
+
description: "Just tells AI to call `knowns agents guideline` for rules"
|
|
43687
43695
|
}
|
|
43688
43696
|
],
|
|
43689
43697
|
initial: 0
|
|
@@ -43775,10 +43783,10 @@ async function updateFiles(files, guidelines) {
|
|
|
43775
43783
|
}
|
|
43776
43784
|
console.log();
|
|
43777
43785
|
}
|
|
43778
|
-
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("--
|
|
43786
|
+
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("--minimal", "Use minimal instruction (default: full embedded guidelines)").option("--all", "Update all instruction files (including Gemini, Copilot)").action(async (options2) => {
|
|
43779
43787
|
try {
|
|
43780
43788
|
const type = options2.type === "mcp" ? "mcp" : "cli";
|
|
43781
|
-
const variant = options2.
|
|
43789
|
+
const variant = options2.minimal ? "instruction" : "general";
|
|
43782
43790
|
const guidelines = getGuidelines(type, variant);
|
|
43783
43791
|
const filesToUpdate = options2.all ? INSTRUCTION_FILES : INSTRUCTION_FILES.filter((f) => f.selected);
|
|
43784
43792
|
const variantLabel = variant === "instruction" ? " (minimal)" : " (full)";
|
|
@@ -71008,7 +71016,7 @@ async function notifyCliUpdate(options2) {
|
|
|
71008
71016
|
// package.json
|
|
71009
71017
|
var package_default = {
|
|
71010
71018
|
name: "knowns",
|
|
71011
|
-
version: "0.8.
|
|
71019
|
+
version: "0.8.6",
|
|
71012
71020
|
description: "AI-native task and documentation management for dev teams",
|
|
71013
71021
|
module: "index.ts",
|
|
71014
71022
|
type: "module",
|
|
@@ -71096,7 +71104,7 @@ var package_default = {
|
|
|
71096
71104
|
marked: "^17.0.1",
|
|
71097
71105
|
prompts: "^2.4.2",
|
|
71098
71106
|
react: "^19.2.3",
|
|
71099
|
-
"react-diff-viewer": "^
|
|
71107
|
+
"react-diff-viewer-continued-react19": "^1.0.0",
|
|
71100
71108
|
"react-dom": "^19.2.3",
|
|
71101
71109
|
sonner: "^2.0.7",
|
|
71102
71110
|
"tailwind-merge": "^3.4.0",
|
|
@@ -71105,12 +71113,6 @@ var package_default = {
|
|
|
71105
71113
|
"unist-util-visit": "^5.0.0",
|
|
71106
71114
|
zod: "^4.2.1"
|
|
71107
71115
|
},
|
|
71108
|
-
overrides: {
|
|
71109
|
-
"react-diff-viewer": {
|
|
71110
|
-
react: "$react",
|
|
71111
|
-
"react-dom": "$react-dom"
|
|
71112
|
-
}
|
|
71113
|
-
},
|
|
71114
71116
|
devDependencies: {
|
|
71115
71117
|
"@biomejs/biome": "^1.9.4",
|
|
71116
71118
|
"@tailwindcss/vite": "^4.1.18",
|
package/dist/mcp/server.js
CHANGED
|
@@ -33128,19 +33128,22 @@ async function handleSearchDocs(args) {
|
|
|
33128
33128
|
var core_rules_default = '# Core Rules\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n---\n\n## \u{1F3AF} The Golden Rule\n\n**If you want to change ANYTHING in a task or doc, use CLI commands or MCP tools. NEVER edit .md files directly.**\n\nWhy? Direct file editing breaks metadata synchronization, Git tracking, and relationships.\n\n---\n\n## \u26A0\uFE0F CRITICAL: The -a Flag Confusion\n\nThe `-a` flag means DIFFERENT things in different commands:\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `task edit` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `doc edit` | `--append` (append content) | ~~assignee~~ |\n\n### Acceptance Criteria: Use --ac\n\n```bash\n# \u274C WRONG: -a is assignee, NOT acceptance criteria!\nknowns task edit 35 -a "- [ ] Criterion" # Sets assignee to garbage!\nknowns task create "Title" -a "Criterion" # Sets assignee to garbage!\n\n# \u2705 CORRECT: Use --ac for acceptance criteria\nknowns task edit 35 --ac "Criterion one"\nknowns task edit 35 --ac "Criterion two"\nknowns task create "Title" --ac "Criterion one" --ac "Criterion two"\n```\n\n---\n\n## Core Principles\n\n| Rule | Description |\n|------|-------------|\n| **CLI/MCP Only** | Use commands for ALL operations. NEVER edit .md files directly |\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Always start timer when taking task, stop when done |\n| **Plan Approval** | Share plan with user, WAIT for approval before coding |\n| **Check AC After Work** | Only mark acceptance criteria done AFTER completing the work |\n\n---\n\n## The --plain Flag\n\n**ONLY for view/list/search commands (NOT create/edit):**\n\n```bash\n# \u2705 CORRECT\nknowns task <id> --plain\nknowns task list --plain\nknowns doc "path" --plain\nknowns doc list --plain\nknowns search "query" --plain\n\n# \u274C WRONG (create/edit don\'t support --plain)\nknowns task create "Title" --plain # ERROR!\nknowns task edit <id> -s done --plain # ERROR!\nknowns doc create "Title" --plain # ERROR!\nknowns doc edit "name" -c "..." --plain # ERROR!\n```\n\n---\n\n## Reference System\n\n| Context | Task Format | Doc Format |\n|---------|-------------|------------|\n| **Writing** (input) | `@task-<id>` | `@doc/<path>` |\n| **Reading** (output) | `@.knowns/tasks/task-<id>` | `@.knowns/docs/<path>.md` |\n\nFollow refs recursively until complete context gathered.\n\n---\n\n## Task IDs\n\n| Format | Example | Notes |\n|--------|---------|-------|\n| Sequential | `48`, `49` | Legacy numeric |\n| Hierarchical | `48.1`, `48.2` | Legacy subtasks |\n| Random | `qkh5ne` | Current (6-char) |\n\n**CRITICAL:** Use raw ID for `--parent`:\n```bash\n# \u2705 CORRECT\nknowns task create "Title" --parent 48\n\n# \u274C WRONG\nknowns task create "Title" --parent task-48\n```\n\n---\n\n## Status & Priority\n\n| Status | When |\n|--------|------|\n| `todo` | Not started (default) |\n| `in-progress` | Currently working |\n| `in-review` | PR submitted |\n| `blocked` | Waiting on dependency |\n| `done` | All criteria met |\n\n| Priority | Level |\n|----------|-------|\n| `low` | Nice-to-have |\n| `medium` | Normal (default) |\n| `high` | Urgent |\n';
|
|
33129
33129
|
|
|
33130
33130
|
// src/templates/guidelines/commands-reference.md
|
|
33131
|
-
var commands_reference_default = '#
|
|
33131
|
+
var commands_reference_default = '# Commands Reference\n\n## task create\n\n```bash\nknowns task create <title> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--description` | `-d` | Task description |\n| `--ac` | | Acceptance criterion (repeatable) |\n| `--labels` | `-l` | Comma-separated labels |\n| `--assignee` | `-a` | Assign to user \u26A0\uFE0F |\n| `--priority` | | low/medium/high |\n| `--status` | `-s` | Initial status |\n| `--parent` | | Parent task ID (raw ID only!) |\n\n**\u26A0\uFE0F `-a` = assignee, NOT acceptance criteria! Use `--ac` for AC.**\n\n---\n\n## task edit\n\n```bash\nknowns task edit <id> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--title` | `-t` | Change title |\n| `--description` | `-d` | Change description |\n| `--status` | `-s` | Change status |\n| `--priority` | | Change priority |\n| `--labels` | `-l` | Set labels |\n| `--assignee` | `-a` | Assign user \u26A0\uFE0F |\n| `--parent` | | Move to parent |\n| `--ac` | | Add acceptance criterion |\n| `--check-ac` | | Mark AC done (1-indexed) |\n| `--uncheck-ac` | | Unmark AC (1-indexed) |\n| `--remove-ac` | | Delete AC (1-indexed) |\n| `--plan` | | Set implementation plan |\n| `--notes` | | Replace notes |\n| `--append-notes` | | Add to notes |\n\n**\u26A0\uFE0F `-a` = assignee, NOT acceptance criteria! Use `--ac` for AC.**\n\n---\n\n## task view/list\n\n```bash\nknowns task <id> --plain # View single task\nknowns task list --plain # List all\nknowns task list --status in-progress --plain\nknowns task list --assignee @me --plain\nknowns task list --tree --plain # Tree hierarchy\n```\n\n---\n\n## doc create\n\n```bash\nknowns doc create <title> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--description` | `-d` | Description |\n| `--tags` | `-t` | Comma-separated tags |\n| `--folder` | `-f` | Folder path |\n\n---\n\n## doc edit\n\n```bash\nknowns doc edit <name> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--title` | `-t` | Change title |\n| `--description` | `-d` | Change description |\n| `--tags` | | Set tags |\n| `--content` | `-c` | Replace content |\n| `--append` | `-a` | Append content \u26A0\uFE0F |\n| `--content-file` | | Content from file |\n| `--append-file` | | Append from file |\n\n**\u26A0\uFE0F In doc edit, `-a` = append content, NOT assignee!**\n\n---\n\n## doc view/list\n\n```bash\nknowns doc <path> --plain # View single doc\nknowns doc list --plain # List all\nknowns doc list --tag api --plain # Filter by tag\n```\n\n---\n\n## time\n\n```bash\nknowns time start <id> # REQUIRED when taking task\nknowns time stop # REQUIRED when completing\nknowns time pause\nknowns time resume\nknowns time status\nknowns time add <id> <duration> -n "Note" -d "2025-01-01"\n```\n\n---\n\n## search\n\n```bash\nknowns search "query" --plain\nknowns search "auth" --type task --plain\nknowns search "api" --type doc --plain\nknowns search "bug" --type task --status in-progress --priority high --plain\n```\n\n---\n\n## Multi-line Input (Bash/Zsh)\n\n```bash\nknowns task edit <id> --plan $\'1. Step\\n2. Step\\n3. Step\'\n```\n';
|
|
33132
33132
|
|
|
33133
33133
|
// src/templates/guidelines/workflow-completion.md
|
|
33134
|
-
var workflow_completion_default = '# Task Completion
|
|
33134
|
+
var workflow_completion_default = '# Task Completion\n\n## Definition of Done\n\nA task is **Done** when ALL of these are complete:\n\n| Requirement | Command |\n|-------------|---------|\n| All AC checked | `knowns task edit <id> --check-ac N` |\n| Notes added | `knowns task edit <id> --notes "Summary"` |\n| Timer stopped | `knowns time stop` |\n| Status = done | `knowns task edit <id> -s done` |\n| Tests pass | Run test suite |\n\n---\n\n## Completion Steps\n\n```bash\n# 1. Verify all AC are checked\nknowns task <id> --plain\n\n# 2. Add implementation notes\nknowns task edit <id> --notes $\'## Summary\nWhat was done and key decisions.\'\n\n# 3. Stop timer (REQUIRED!)\nknowns time stop\n\n# 4. Mark done\nknowns task edit <id> -s done\n```\n\n---\n\n## Post-Completion Changes\n\nIf user requests changes after task is done:\n\n```bash\nknowns task edit <id> -s in-progress # Reopen\nknowns time start <id> # Restart timer\nknowns task edit <id> --ac "Fix: description"\nknowns task edit <id> --append-notes "\u{1F504} Reopened: reason"\n# Complete work, then follow completion steps again\n```\n\n---\n\n## Checklist\n\n- [ ] All AC checked (`--check-ac`)\n- [ ] Notes added (`--notes`)\n- [ ] Timer stopped (`time stop`)\n- [ ] Tests pass\n- [ ] Status = done (`-s done`)\n';
|
|
33135
33135
|
|
|
33136
33136
|
// src/templates/guidelines/workflow-creation.md
|
|
33137
|
-
var workflow_creation_default = '# Task Creation
|
|
33137
|
+
var workflow_creation_default = '# Task Creation\n\n## Before Creating\n\n```bash\n# Search for existing tasks first\nknowns search "keyword" --type task --plain\n```\n\n---\n\n## Create Task\n\n```bash\nknowns task create "Clear title (WHAT)" \\\n -d "Description (WHY)" \\\n --ac "Outcome 1" \\\n --ac "Outcome 2" \\\n --priority medium \\\n -l "labels"\n```\n\n---\n\n## Quality Guidelines\n\n### Title\n| \u274C Bad | \u2705 Good |\n|--------|---------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout |\n\n### Description\nExplain WHY. Include doc refs: `@doc/security-patterns`\n\n### Acceptance Criteria\n**Outcome-focused, NOT implementation steps:**\n\n| \u274C Bad | \u2705 Good |\n|--------|---------|\n| Add handleLogin() function | User can login |\n| Use bcrypt | Passwords are hashed |\n| Add try-catch | Errors return proper HTTP codes |\n\n---\n\n## Subtasks\n\n```bash\nknowns task create "Parent task"\nknowns task create "Subtask" --parent 48 # Raw ID only!\n```\n\n---\n\n## Anti-Patterns\n\n- \u274C Too many AC in one task \u2192 Split into multiple tasks\n- \u274C Implementation steps as AC \u2192 Write outcomes instead\n- \u274C Skip search \u2192 Always check existing tasks first\n';
|
|
33138
33138
|
|
|
33139
33139
|
// src/templates/guidelines/workflow-execution.md
|
|
33140
|
-
var workflow_execution_default = '# Task Execution
|
|
33140
|
+
var workflow_execution_default = '# Task Execution\n\n## Step 1: Take Task\n\n```bash\nknowns task edit <id> -s in-progress -a @me\nknowns time start <id> # REQUIRED!\n```\n\n---\n\n## Step 2: Research\n\n```bash\n# Read task and follow ALL refs\nknowns task <id> --plain\n# @.knowns/docs/xxx.md \u2192 knowns doc "xxx" --plain\n# @.knowns/tasks/task-YY \u2192 knowns task YY --plain\n\n# Search related docs\nknowns search "keyword" --type doc --plain\n\n# Check similar done tasks\nknowns search "keyword" --type task --status done --plain\n```\n\n---\n\n## Step 3: Plan (BEFORE coding!)\n\n```bash\nknowns task edit <id> --plan $\'1. Research (see @doc/xxx)\n2. Implement\n3. Test\n4. Document\'\n```\n\n**\u26A0\uFE0F Share plan with user. WAIT for approval before coding.**\n\n---\n\n## Step 4: Implement\n\n```bash\n# Check AC only AFTER work is done\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "\u2713 Done: feature X"\n```\n\n---\n\n## Scope Changes\n\nIf new requirements emerge during work:\n\n```bash\n# Small: Add to current task\nknowns task edit <id> --ac "New requirement"\nknowns task edit <id> --append-notes "\u26A0\uFE0F Scope updated: reason"\n\n# Large: Ask user first, then create follow-up\nknowns task create "Follow-up: feature" -d "From task <id>"\n```\n\n**\u26A0\uFE0F Don\'t silently expand scope. Ask user first.**\n\n---\n\n## Key Rules\n\n1. **Plan before code** - Capture approach first\n2. **Wait for approval** - Don\'t start without OK\n3. **Check AC after work** - Not before\n4. **Ask on scope changes** - Don\'t expand silently\n';
|
|
33141
33141
|
|
|
33142
33142
|
// src/templates/guidelines/common-mistakes.md
|
|
33143
|
-
var common_mistakes_default = '# Common Mistakes\n\
|
|
33143
|
+
var common_mistakes_default = '# Common Mistakes\n\n## \u26A0\uFE0F CRITICAL: The -a Flag\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create/edit` | `--assignee` | ~~acceptance criteria~~ |\n| `doc edit` | `--append` | ~~assignee~~ |\n\n```bash\n# \u274C WRONG (sets assignee to garbage!)\nknowns task edit 35 -a "Criterion text"\n\n# \u2705 CORRECT (use --ac)\nknowns task edit 35 --ac "Criterion text"\n```\n\n---\n\n## Quick Reference\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| Edit .md files directly | Use CLI commands |\n| `-a "criterion"` | `--ac "criterion"` |\n| `--parent task-48` | `--parent 48` (raw ID) |\n| `--plain` with create/edit | `--plain` only for view/list |\n| Check AC before work done | Check AC AFTER work done |\n| Code before plan approval | Wait for user approval |\n| Code before reading docs | Read docs FIRST |\n| Skip time tracking | Always `time start`/`stop` |\n| Ignore task refs | Follow ALL `@.knowns/...` refs |\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\n| Set assignee to AC text | `knowns task edit <id> -a @me` |\n| Forgot to stop timer | `knowns time add <id> <duration>` |\n| Checked AC too early | `knowns task edit <id> --uncheck-ac N` |\n| Task not found | `knowns task list --plain` |\n';
|
|
33144
|
+
|
|
33145
|
+
// src/templates/guidelines/context-optimization.md
|
|
33146
|
+
var context_optimization_default = '# Context Optimization\n\nOptimize your context usage to work more efficiently within token limits.\n\n---\n\n## Output Format\n\n```bash\n# \u274C Verbose output\nknowns task 42 --json\n\n# \u2705 Compact output (always use --plain)\nknowns task 42 --plain\n```\n\n---\n\n## Search Before Read\n\n```bash\n# \u274C Reading all docs to find info\nknowns doc "doc1" --plain\nknowns doc "doc2" --plain\nknowns doc "doc3" --plain\n\n# \u2705 Search first, then read only relevant docs\nknowns search "authentication" --type doc --plain\nknowns doc "security-patterns" --plain # Only the relevant one\n```\n\n---\n\n## Selective File Reading\n\n```bash\n# \u274C Reading entire large file\nRead file (2000+ lines)\n\n# \u2705 Read specific sections\nRead file with offset=100 limit=50\n```\n\n---\n\n## Compact Notes\n\n```bash\n# \u274C Verbose notes\nknowns task edit 42 --append-notes "I have successfully completed the implementation of the authentication middleware which validates JWT tokens and handles refresh logic..."\n\n# \u2705 Compact notes\nknowns task edit 42 --append-notes "\u2713 Auth middleware + JWT validation done"\n```\n\n---\n\n## Avoid Redundant Operations\n\n| Don\'t | Do Instead |\n|-------|------------|\n| Re-read files already in context | Reference from memory |\n| List tasks/docs multiple times | List once, remember results |\n| Quote entire file contents | Summarize key points |\n| Repeat full error messages | Reference error briefly |\n\n---\n\n## Efficient Workflow\n\n| Phase | Context-Efficient Approach |\n|-------|---------------------------|\n| **Research** | Search \u2192 Read only matches |\n| **Planning** | Brief plan, not detailed prose |\n| **Coding** | Read only files being modified |\n| **Notes** | Bullet points, not paragraphs |\n| **Completion** | Summary, not full log |\n\n---\n\n## Quick Rules\n\n1. **Always `--plain`** - Never use `--json` unless specifically needed\n2. **Search first** - Don\'t read all docs hoping to find info\n3. **Read selectively** - Use offset/limit for large files\n4. **Write concise** - Compact notes, not essays\n5. **Don\'t repeat** - Reference context already loaded\n6. **Summarize** - Key points, not full quotes\n';
|
|
33144
33147
|
|
|
33145
33148
|
// src/templates/guidelines/index.ts
|
|
33146
33149
|
var CORE_RULES = core_rules_default.trim();
|
|
@@ -33149,6 +33152,7 @@ var WORKFLOW_CREATION = workflow_creation_default.trim();
|
|
|
33149
33152
|
var WORKFLOW_EXECUTION = workflow_execution_default.trim();
|
|
33150
33153
|
var WORKFLOW_COMPLETION = workflow_completion_default.trim();
|
|
33151
33154
|
var COMMON_MISTAKES = common_mistakes_default.trim();
|
|
33155
|
+
var CONTEXT_OPTIMIZATION = context_optimization_default.trim();
|
|
33152
33156
|
var Guidelines = {
|
|
33153
33157
|
// Core rules - always needed
|
|
33154
33158
|
core: CORE_RULES,
|
|
@@ -33162,6 +33166,8 @@ var Guidelines = {
|
|
|
33162
33166
|
},
|
|
33163
33167
|
// Common mistakes
|
|
33164
33168
|
mistakes: COMMON_MISTAKES,
|
|
33169
|
+
// Context optimization
|
|
33170
|
+
contextOptimization: CONTEXT_OPTIMIZATION,
|
|
33165
33171
|
/**
|
|
33166
33172
|
* Get full guidelines (all sections combined)
|
|
33167
33173
|
*/
|
|
@@ -33169,6 +33175,8 @@ var Guidelines = {
|
|
|
33169
33175
|
const content = [
|
|
33170
33176
|
CORE_RULES,
|
|
33171
33177
|
"---",
|
|
33178
|
+
CONTEXT_OPTIMIZATION,
|
|
33179
|
+
"---",
|
|
33172
33180
|
COMMANDS_REFERENCE,
|
|
33173
33181
|
"---",
|
|
33174
33182
|
WORKFLOW_CREATION,
|
|
@@ -33187,16 +33195,16 @@ ${content}
|
|
|
33187
33195
|
return content;
|
|
33188
33196
|
},
|
|
33189
33197
|
/**
|
|
33190
|
-
* Get compact guidelines (core + mistakes only)
|
|
33198
|
+
* Get compact guidelines (core + context optimization + mistakes only)
|
|
33191
33199
|
*/
|
|
33192
33200
|
getCompact() {
|
|
33193
|
-
return [CORE_RULES, "---", COMMON_MISTAKES].join("\n\n");
|
|
33201
|
+
return [CORE_RULES, "---", CONTEXT_OPTIMIZATION, "---", COMMON_MISTAKES].join("\n\n");
|
|
33194
33202
|
},
|
|
33195
33203
|
/**
|
|
33196
33204
|
* Get guidelines for specific workflow stage
|
|
33197
33205
|
*/
|
|
33198
33206
|
getForStage(stage) {
|
|
33199
|
-
const sections = [CORE_RULES, "---"];
|
|
33207
|
+
const sections = [CORE_RULES, "---", CONTEXT_OPTIMIZATION, "---"];
|
|
33200
33208
|
switch (stage) {
|
|
33201
33209
|
case "creation":
|
|
33202
33210
|
sections.push(WORKFLOW_CREATION);
|