knowns 0.8.2 → 0.8.3

package/dist/index.js

@@ -43475,20 +43475,114 @@ import { mkdir as mkdir3, readFile as readFile2, writeFile as writeFile2 } from
 import { dirname, join as join3 } from "node:path";
 var import_prompts = __toESM(require_prompts3(), 1);
 
-// src/templates/cli/general.md
-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';
-
-// src/templates/cli/instruction.md
-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";
+// src/templates/guidelines/core-rules.md
+var core_rules_default = '# Core Rules\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n---\n\n## \u{1F3AF} The Golden Rule\n\n**If you want to change ANYTHING in a task or doc, use CLI commands or MCP tools. NEVER edit .md files directly.**\n\nWhy? Direct file editing breaks metadata synchronization, Git tracking, and relationships.\n\n---\n\n## \u26A0\uFE0F CRITICAL: The -a Flag Confusion\n\nThe `-a` flag means DIFFERENT things in different commands:\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `task edit` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `doc edit` | `--append` (append content) | ~~assignee~~ |\n\n### Acceptance Criteria: Use --ac\n\n```bash\n# \u274C WRONG: -a is assignee, NOT acceptance criteria!\nknowns task edit 35 -a "- [ ] Criterion"    # Sets assignee to garbage!\nknowns task create "Title" -a "Criterion"   # Sets assignee to garbage!\n\n# \u2705 CORRECT: Use --ac for acceptance criteria\nknowns task edit 35 --ac "Criterion one"\nknowns task edit 35 --ac "Criterion two"\nknowns task create "Title" --ac "Criterion one" --ac "Criterion two"\n```\n\n---\n\n## Core Principles\n\n| Rule | Description |\n|------|-------------|\n| **CLI/MCP Only** | Use commands for ALL operations. NEVER edit .md files directly |\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Always start timer when taking task, stop when done |\n| **Plan Approval** | Share plan with user, WAIT for approval before coding |\n| **Check AC After Work** | Only mark acceptance criteria done AFTER completing the work |\n\n---\n\n## The --plain Flag\n\n**ONLY for view/list/search commands (NOT create/edit):**\n\n```bash\n# \u2705 CORRECT\nknowns task <id> --plain\nknowns task list --plain\nknowns doc "path" --plain\nknowns doc list --plain\nknowns search "query" --plain\n\n# \u274C WRONG (create/edit don\'t support --plain)\nknowns task create "Title" --plain       # ERROR!\nknowns task edit <id> -s done --plain    # ERROR!\nknowns doc create "Title" --plain        # ERROR!\nknowns doc edit "name" -c "..." --plain  # ERROR!\n```\n\n---\n\n## Reference System\n\n| Context | Task Format | Doc Format |\n|---------|-------------|------------|\n| **Writing** (input) | `@task-<id>` | `@doc/<path>` |\n| **Reading** (output) | `@.knowns/tasks/task-<id>` | `@.knowns/docs/<path>.md` |\n\nFollow refs recursively until complete context gathered.\n\n---\n\n## Task IDs\n\n| Format | Example | Notes |\n|--------|---------|-------|\n| Sequential | `48`, `49` | Legacy numeric |\n| Hierarchical | `48.1`, `48.2` | Legacy subtasks |\n| Random | `qkh5ne` | Current (6-char) |\n\n**CRITICAL:** Use raw ID for `--parent`:\n```bash\n# \u2705 CORRECT\nknowns task create "Title" --parent 48\n\n# \u274C WRONG\nknowns task create "Title" --parent task-48\n```\n\n---\n\n## Status & Priority\n\n| Status | When |\n|--------|------|\n| `todo` | Not started (default) |\n| `in-progress` | Currently working |\n| `in-review` | PR submitted |\n| `blocked` | Waiting on dependency |\n| `done` | All criteria met |\n\n| Priority | Level |\n|----------|-------|\n| `low` | Nice-to-have |\n| `medium` | Normal (default) |\n| `high` | Urgent |\n';
+
+// src/templates/guidelines/commands-reference.md
+var commands_reference_default = '# CLI Commands Reference\n\nComplete reference for all Knowns CLI commands.\n\n---\n\n## Task Commands\n\n### task create\n\n```\nknowns task create <title> [options]\n```\n\n| Flag | Short | Purpose | Example |\n|------|-------|---------|---------|\n| `--description` | `-d` | Task description | `-d "Fix the login bug"` |\n| `--ac` | | Acceptance criterion (repeatable) | `--ac "User can login"` |\n| `--labels` | `-l` | Comma-separated labels | `-l "bug,urgent"` |\n| `--assignee` | `-a` | Assign to user | `-a @username` |\n| `--priority` | | low/medium/high | `--priority high` |\n| `--status` | `-s` | Initial status | `-s todo` |\n| `--parent` | | Parent task ID (raw ID only!) | `--parent 48` |\n\n**Example:**\n```bash\nknowns task create "Fix login timeout" \\\n  -d "Users experience timeout on slow networks" \\\n  --ac "Login works on 3G connection" \\\n  --ac "Timeout increased to 30s" \\\n  -l "bug,auth" \\\n  --priority high\n```\n\n---\n\n### task edit\n\n```\nknowns task edit <id> [options]\n```\n\n| Flag | Short | Purpose | Example |\n|------|-------|---------|---------|\n| `--title` | `-t` | Change title | `-t "New title"` |\n| `--description` | `-d` | Change description | `-d "New desc"` |\n| `--status` | `-s` | Change status | `-s in-progress` |\n| `--priority` | | Change priority | `--priority high` |\n| `--labels` | `-l` | Set labels | `-l "bug,urgent"` |\n| `--assignee` | `-a` | Assign user \u26A0\uFE0F | `-a @username` |\n| `--parent` | | Move to parent | `--parent 48` |\n| `--ac` | | Add acceptance criterion | `--ac "New criterion"` |\n| `--check-ac` | | Mark AC done (1-indexed) | `--check-ac 1` |\n| `--uncheck-ac` | | Unmark AC (1-indexed) | `--uncheck-ac 1` |\n| `--remove-ac` | | Delete AC (1-indexed) | `--remove-ac 3` |\n| `--plan` | | Set implementation plan | `--plan "1. Step one"` |\n| `--notes` | | Replace notes | `--notes "Summary"` |\n| `--append-notes` | | Add to notes | `--append-notes "\u2713 Done"` |\n\n**\u26A0\uFE0F WARNING:** `-a` is assignee, NOT acceptance criteria! Use `--ac` for AC.\n\n**Examples:**\n```bash\n# Take task\nknowns task edit abc123 -s in-progress -a @me\n\n# Add acceptance criteria (use --ac, NOT -a!)\nknowns task edit abc123 --ac "Feature works offline"\n\n# Check criteria as done (1-indexed)\nknowns task edit abc123 --check-ac 1 --check-ac 2\n\n# Add implementation plan\nknowns task edit abc123 --plan $\'1. Research\\n2. Implement\\n3. Test\'\n\n# Add progress notes\nknowns task edit abc123 --append-notes "\u2713 Completed research phase"\n\n# Complete task\nknowns task edit abc123 -s done\n```\n\n---\n\n### task view/list\n\n```bash\n# View single task (ALWAYS use --plain for AI)\nknowns task <id> --plain\nknowns task view <id> --plain\n\n# List tasks\nknowns task list --plain\nknowns task list --status in-progress --plain\nknowns task list --assignee @me --plain\nknowns task list --tree --plain\n```\n\n---\n\n## Doc Commands\n\n### doc create\n\n```\nknowns doc create <title> [options]\n```\n\n| Flag | Short | Purpose | Example |\n|------|-------|---------|---------|\n| `--description` | `-d` | Description | `-d "API reference"` |\n| `--tags` | `-t` | Comma-separated tags | `-t "api,reference"` |\n| `--folder` | `-f` | Folder path | `-f "guides"` |\n\n**Example:**\n```bash\nknowns doc create "API Reference" \\\n  -d "REST API documentation" \\\n  -t "api,docs" \\\n  -f "api"\n```\n\n---\n\n### doc edit\n\n```\nknowns doc edit <name> [options]\n```\n\n| Flag | Short | Purpose | Example |\n|------|-------|---------|---------|\n| `--title` | `-t` | Change title | `-t "New Title"` |\n| `--description` | `-d` | Change description | `-d "New desc"` |\n| `--tags` | | Set tags | `--tags "new,tags"` |\n| `--content` | `-c` | Replace content | `-c "New content"` |\n| `--append` | `-a` | Append content \u26A0\uFE0F | `-a "Added section"` |\n| `--content-file` | | Content from file | `--content-file ./content.md` |\n| `--append-file` | | Append from file | `--append-file ./more.md` |\n\n**\u26A0\uFE0F NOTE:** In doc edit, `-a` means append content, NOT assignee!\n\n**Examples:**\n```bash\n# Replace content\nknowns doc edit "readme" -c "# New Content"\n\n# Append content\nknowns doc edit "readme" -a "## New Section"\n```\n\n---\n\n### doc view/list\n\n```bash\n# View doc (ALWAYS use --plain for AI)\nknowns doc <path> --plain\nknowns doc view "<path>" --plain\n\n# List docs\nknowns doc list --plain\nknowns doc list --tag api --plain\nknowns doc list "guides/" --plain\n```\n\n---\n\n## Time Commands\n\n```bash\n# Start timer (REQUIRED when taking task)\nknowns time start <taskId>\n\n# Stop timer (REQUIRED when completing task)\nknowns time stop\n\n# Pause/resume\nknowns time pause\nknowns time resume\n\n# Check status\nknowns time status\n\n# Manual entry\nknowns time add <taskId> <duration> -n "Note" -d "2025-01-01"\n# duration: "2h", "30m", "1h30m"\n\n# Report\nknowns time report --from "2025-01-01" --to "2025-12-31"\n```\n\n---\n\n## Search Commands\n\n```bash\n# Search everything\nknowns search "query" --plain\n\n# Search by type\nknowns search "auth" --type task --plain\nknowns search "api" --type doc --plain\n\n# Filter by status/priority\nknowns search "bug" --type task --status in-progress --priority high --plain\n```\n\n---\n\n## Multi-line Input\n\nDifferent shells handle multi-line strings differently:\n\n**Bash/Zsh (ANSI-C quoting):**\n```bash\nknowns task edit <id> --plan $\'1. Step one\\n2. Step two\\n3. Step three\'\n```\n\n**PowerShell:**\n```powershell\nknowns task edit <id> --plan "1. Step one`n2. Step two`n3. Step three"\n```\n\n**Cross-platform (heredoc):**\n```bash\nknowns task edit <id> --plan "$(cat <<EOF\n1. Step one\n2. Step two\n3. Step three\nEOF\n)"\n```\n\n---\n\n## MCP Tools (Alternative to CLI)\n\n| Action | MCP Tool |\n|--------|----------|\n| List tasks | `list_tasks({})` |\n| Get task | `get_task({ taskId })` |\n| Create task | `create_task({ title, description, priority, labels })` |\n| Update task | `update_task({ taskId, status, assignee, plan, notes })` |\n| Search tasks | `search_tasks({ query })` |\n| List docs | `list_docs({})` |\n| Get doc | `get_doc({ path })` |\n| Create doc | `create_doc({ title, description, tags, folder })` |\n| Update doc | `update_doc({ path, content, appendContent })` |\n| Start timer | `start_time({ taskId })` |\n| Stop timer | `stop_time({ taskId })` |\n\n**Note:** MCP does NOT support acceptance criteria operations. Use CLI:\n```bash\nknowns task edit <id> --ac "criterion"\nknowns task edit <id> --check-ac 1\n```\n';
+
+// src/templates/guidelines/workflow-completion.md
+var workflow_completion_default = '# Task Completion Workflow\n\nGuide for properly completing tasks.\n\n---\n\n## Definition of Done\n\nA task is **Done** ONLY when **ALL** of the following are complete:\n\n### \u2705 Via CLI Commands\n\n| Requirement | Command | Status |\n|-------------|---------|--------|\n| All AC checked | `knowns task edit <id> --check-ac N` | Required |\n| Implementation notes added | `knowns task edit <id> --notes "..."` | Required |\n| Timer stopped | `knowns time stop` | Required |\n| Status set to done | `knowns task edit <id> -s done` | Required |\n\n### \u2705 Via Code/Testing\n\n| Requirement | Action | Status |\n|-------------|--------|--------|\n| Tests pass | Run test suite | Required |\n| No regressions | Verify existing functionality | Required |\n| Docs updated | Update relevant documentation | If applicable |\n| Code reviewed | Self-review changes | Required |\n\n---\n\n## Completion Steps\n\n### Step 1: Verify All Acceptance Criteria\n\n```bash\n# View the task to check AC status\nknowns task <id> --plain\n\n# Ensure ALL criteria are checked\n# If any are unchecked, complete the work first!\n```\n\n### Step 2: Add Implementation Notes\n\nWrite notes suitable for a PR description:\n\n```bash\nknowns task edit <id> --notes $\'## Summary\nImplemented JWT authentication using jsonwebtoken library.\n\n## Changes\n- Added auth middleware in src/middleware/auth.ts\n- Added /login and /refresh endpoints\n- Created JWT utility functions\n\n## Tests\n- Added 15 unit tests\n- Coverage: 94%\n\n## Notes\n- Chose HS256 algorithm for simplicity\n- Token expiry set to 1 hour as per requirements\'\n```\n\n**Good notes include:**\n- What was implemented\n- Key decisions and why\n- Files changed\n- Test coverage\n- Any follow-up needed\n\n### Step 3: Stop Timer\n\n```bash\nknowns time stop\n```\n\n**\u26A0\uFE0F CRITICAL:** Never forget to stop the timer!\n\nIf you forgot to stop earlier, add manual entry:\n```bash\nknowns time add <id> 2h -n "Forgot to stop timer"\n```\n\n### Step 4: Mark as Done\n\n```bash\nknowns task edit <id> -s done\n```\n\n---\n\n## Post-Completion Changes\n\nIf the user requests changes **AFTER** the task is marked done:\n\n```bash\n# 1. Reopen task\nknowns task edit <id> -s in-progress\n\n# 2. Restart timer\nknowns time start <id>\n\n# 3. Add AC for the changes\nknowns task edit <id> --ac "Post-completion fix: description"\n\n# 4. Document why reopened\nknowns task edit <id> --append-notes "\u{1F504} Reopened: User requested changes - reason"\n\n# 5. Complete the work, then follow completion steps again\n```\n\n---\n\n## Knowledge Extraction\n\nAfter completing a task, consider if any knowledge should be documented:\n\n```bash\n# Search if similar pattern already documented\nknowns search "pattern-name" --type doc --plain\n\n# If new reusable knowledge, create doc\nknowns doc create "Pattern: Name" \\\n  -d "Reusable pattern from task implementation" \\\n  -t "pattern" \\\n  -f "patterns"\n\n# Reference source task\nknowns doc edit "patterns/name" -a "Source: @task-<id>"\n```\n\n**Extract knowledge when:**\n- New patterns/conventions discovered\n- Common error solutions found\n- Reusable code approaches identified\n- Integration patterns documented\n\n**Don\'t extract:**\n- Task-specific details (those belong in implementation notes)\n- One-off solutions\n\n---\n\n## Common Mistakes\n\n### \u274C Marking done without all AC checked\n\n```bash\n# \u274C Wrong: AC not all checked\nknowns task edit <id> -s done\n\n# \u2705 Right: Check all AC first\nknowns task edit <id> --check-ac 1 --check-ac 2 --check-ac 3\nknowns task edit <id> -s done\n```\n\n### \u274C Forgetting to stop timer\n\nTimer keeps running! Always stop when done:\n```bash\nknowns time stop\n```\n\n### \u274C No implementation notes\n\nNotes are required for PR description:\n```bash\n# \u274C Wrong: No notes\nknowns task edit <id> -s done\n\n# \u2705 Right: Add notes first\nknowns task edit <id> --notes "Summary of what was done"\nknowns task edit <id> -s done\n```\n\n### \u274C Autonomously creating follow-up tasks\n\nAfter completing work, **present** follow-up ideas to the user. Don\'t automatically create new tasks without permission.\n\n---\n\n## Completion Checklist\n\nBefore marking done, verify:\n\n- [ ] All acceptance criteria are checked (`--check-ac`)\n- [ ] Implementation notes are added (`--notes`)\n- [ ] Implementation plan reflects final approach\n- [ ] Tests pass without regressions\n- [ ] Documentation updated if needed\n- [ ] Timer stopped (`knowns time stop`)\n- [ ] Status set to done (`-s done`)\n';
+
+// src/templates/guidelines/workflow-creation.md
+var workflow_creation_default = '# Task Creation Workflow\n\nGuide for creating well-structured tasks.\n\n---\n\n## Step 1: Search First\n\nBefore creating a new task, check if similar work already exists:\n\n```bash\n# Search for existing tasks\nknowns search "keyword" --type task --plain\n\n# List tasks by status\nknowns task list --status todo --plain\nknowns task list --status in-progress --plain\n```\n\n**Why?** Avoid duplicate work and understand existing context.\n\n---\n\n## Step 2: Assess Scope\n\nAsk yourself:\n- Does this work fit in one PR?\n- Does it span multiple systems?\n- Are there natural breaking points?\n\n**Single task:** Work is focused, affects one area\n**Multiple tasks:** Work spans different subsystems or has phases\n\n---\n\n## Step 3: Create with Proper Structure\n\n### Basic Task Creation\n\n```bash\nknowns task create "Clear title describing what needs to be done" \\\n  -d "Description explaining WHY this is needed" \\\n  --ac "First acceptance criterion" \\\n  --ac "Second acceptance criterion" \\\n  --priority medium \\\n  -l "label1,label2"\n```\n\n### Creating Subtasks\n\n```bash\n# Create parent task first\nknowns task create "Parent feature"\n\n# Create subtasks (use raw ID, not task-XX)\nknowns task create "Subtask 1" --parent 48\nknowns task create "Subtask 2" --parent 48\n```\n\n---\n\n## Task Quality Guidelines\n\n### Title (The "what")\n\nClear, brief summary of the task.\n\n| \u274C Bad | \u2705 Good |\n|--------|---------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout on slow networks |\n| Update docs | Document rate limiting in API.md |\n\n### Description (The "why")\n\nExplains context and purpose. Include doc references.\n\n```markdown\nWe need JWT authentication because sessions don\'t scale\nfor our microservices architecture.\n\nRelated: @doc/security-patterns, @doc/api-guidelines\n```\n\n### Acceptance Criteria (The "what" - outcomes)\n\n**Key Principles:**\n- **Outcome-oriented** - Focus on results, not implementation\n- **Testable** - Can be objectively verified\n- **User-focused** - Frame from end-user perspective\n\n| \u274C Bad (Implementation details) | \u2705 Good (Outcomes) |\n|--------------------------------|-------------------|\n| Add function handleLogin() in auth.ts | User can login and receive JWT token |\n| Use bcrypt for hashing | Passwords are securely hashed |\n| Add try-catch blocks | Errors return appropriate HTTP status codes |\n\n---\n\n## Anti-Patterns to Avoid\n\n### \u274C Don\'t create overly broad tasks\n\n```bash\n# \u274C Too broad - too many ACs\nknowns task create "Build entire auth system" \\\n  --ac "Login" --ac "Logout" --ac "Register" \\\n  --ac "Password reset" --ac "OAuth" --ac "2FA"\n\n# \u2705 Better - split into focused tasks\nknowns task create "Implement user login" --ac "User can login with email/password"\nknowns task create "Implement user registration" --ac "User can create account"\n```\n\n### \u274C Don\'t embed implementation steps in AC\n\n```bash\n# \u274C Implementation steps as AC\n--ac "Create auth.ts file"\n--ac "Add bcrypt dependency"\n--ac "Write handleLogin function"\n\n# \u2705 Outcome-focused AC\n--ac "User can login with valid credentials"\n--ac "Invalid credentials return 401 error"\n--ac "Successful login returns JWT token"\n```\n\n### \u274C Don\'t skip search\n\nAlways search for existing tasks first. You might find:\n- Duplicate task already exists\n- Related task with useful context\n- Completed task with reusable patterns\n\n---\n\n## Report Results\n\nAfter creating tasks, show the user:\n- Task ID\n- Title\n- Description summary\n- Acceptance criteria\n\nThis allows for feedback and corrections before work begins.\n';
+
+// src/templates/guidelines/workflow-execution.md
+var workflow_execution_default = '# Task Execution Workflow\n\nGuide for implementing tasks effectively.\n\n---\n\n## Step 1: Take the Task\n\nThe **first things** you must do when taking a task:\n\n```bash\n# Set status to in-progress and assign to yourself\nknowns task edit <id> -s in-progress -a @me\n\n# Start time tracking (REQUIRED!)\nknowns time start <id>\n```\n\n---\n\n## Step 2: Research & Understand\n\nBefore planning, gather complete context:\n\n```bash\n# Read the task details\nknowns task <id> --plain\n\n# Follow ALL refs in the task\n# @.knowns/docs/xxx.md \u2192 knowns doc "xxx" --plain\n# @.knowns/tasks/task-YY \u2192 knowns task YY --plain\n\n# Search for related documentation\nknowns search "keyword" --type doc --plain\n\n# Check similar completed tasks for patterns\nknowns search "keyword" --type task --status done --plain\n```\n\n**Why?** Understanding existing patterns prevents reinventing the wheel.\n\n---\n\n## Step 3: Create Implementation Plan\n\nCapture your plan in the task **BEFORE writing any code**.\n\n```bash\nknowns task edit <id> --plan $\'1. Research existing patterns (see @doc/xxx)\n2. Design approach\n3. Implement core functionality\n4. Add tests\n5. Update documentation\'\n```\n\n### \u26A0\uFE0F CRITICAL: Wait for Approval\n\n**Share the plan with the user and WAIT for explicit approval before coding.**\n\nDo not begin implementation until:\n- User approves the plan, OR\n- User explicitly tells you to skip review\n\n---\n\n## Step 4: Implement\n\nWork through your plan step by step:\n\n### Document Progress\n\n```bash\n# After completing each significant piece of work\nknowns task edit <id> --append-notes "\u2713 Completed: research phase"\nknowns task edit <id> --append-notes "\u2713 Completed: core implementation"\n```\n\n### Check Acceptance Criteria\n\nOnly mark AC as done **AFTER** the work is actually complete:\n\n```bash\n# After completing work for AC #1\nknowns task edit <id> --check-ac 1\n\n# After completing work for AC #2\nknowns task edit <id> --check-ac 2\n```\n\n**\u26A0\uFE0F CRITICAL:** Never check AC before the work is done. ACs represent completed outcomes.\n\n---\n\n## Scope Management\n\n### When New Requirements Emerge\n\nIf you discover additional work needed during implementation:\n\n**Option 1: Add to current task (if small)**\n```bash\nknowns task edit <id> --ac "New requirement discovered"\nknowns task edit <id> --append-notes "\u26A0\uFE0F Scope updated: Added requirement for X"\n```\n\n**Option 2: Create follow-up task (if significant)**\n```bash\nknowns task create "Follow-up: Additional feature" -d "Discovered during task <id>"\nknowns task edit <id> --append-notes "\u{1F4DD} Created follow-up task for X"\n```\n\n**\u26A0\uFE0F CRITICAL:** Stop and ask the user which option to use. Don\'t silently expand scope.\n\n---\n\n## Plan Updates\n\nIf your approach changes during implementation, update the plan:\n\n```bash\nknowns task edit <id> --plan $\'1. [DONE] Research\n2. [DONE] Original approach\n3. [CHANGED] New approach due to X\n4. Remaining work\'\n```\n\nThe plan should remain the **single source of truth** for how the task was solved.\n\n---\n\n## Handling Subtasks\n\n### When Assigned "Parent and All Subtasks"\n\nProceed sequentially without asking permission between each subtask:\n\n1. Complete subtask 1\n2. Complete subtask 2\n3. Continue until all done\n\n### When Assigned Single Subtask\n\nPresent progress and request guidance before advancing to the next subtask.\n\n---\n\n## Key Principles\n\n1. **Plan before code** - Always capture approach before implementation\n2. **Document decisions** - Record why you chose certain approaches\n3. **Update on changes** - Keep plan current if approach shifts\n4. **Ask on scope** - Don\'t silently expand work\n5. **Check AC after work** - Only mark done when truly complete\n';
+
+// src/templates/guidelines/common-mistakes.md
+var common_mistakes_default = '# Common Mistakes\n\nAnti-patterns and common errors to avoid.\n\n---\n\n## \u26A0\uFE0F CRITICAL: Flag Confusion\n\n### The -a Flag Means Different Things!\n\n| Command | `-a` Flag Means | NOT This! |\n|---------|-----------------|-----------|\n| `task create` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `task edit` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `doc edit` | `--append` (append content) | ~~assignee~~ |\n\n### \u274C WRONG: Using -a for Acceptance Criteria\n\n```bash\n# \u274C WRONG: -a is assignee, sets assignee to garbage text!\nknowns task edit 35 -a "- [ ] Criterion"\nknowns task edit 35 -a "User can login"\nknowns task create "Title" -a "Criterion text"\n```\n\n### \u2705 CORRECT: Using --ac for Acceptance Criteria\n\n```bash\n# \u2705 CORRECT: Use --ac for acceptance criteria\nknowns task edit 35 --ac "Criterion one"\nknowns task edit 35 --ac "Criterion two"\nknowns task create "Title" --ac "Criterion one" --ac "Criterion two"\n```\n\n---\n\n## Quick Reference: DO vs DON\'T\n\n### File Operations\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| Edit .md files directly | Use CLI commands |\n| Change `- [ ]` to `- [x]` in file | `--check-ac <index>` |\n| Add notes directly to file | `--notes` or `--append-notes` |\n| Edit frontmatter manually | Use CLI flags |\n\n### Task Operations\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| `-a "criterion"` (assignee!) | `--ac "criterion"` |\n| `--parent task-48` | `--parent 48` (raw ID) |\n| Skip time tracking | Always `time start`/`time stop` |\n| Check AC before work done | Check AC AFTER completing work |\n| Code before plan approval | Wait for user approval |\n| Code before reading docs | Read ALL related docs first |\n\n### Flag Usage\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| `--plain` with create | `--plain` only for view/list/search |\n| `--plain` with edit | `--plain` only for view/list/search |\n| `--criteria "text"` | `--ac "text"` |\n| `-ac "text"` | `--ac "text"` (two dashes!) |\n\n---\n\n## Detailed Mistakes\n\n### 1. Direct File Editing\n\n```markdown\n# \u274C DON\'T DO THIS:\n1. Open backlog/tasks/task-7.md in editor\n2. Change "- [ ]" to "- [x]" manually\n3. Add notes directly to the file\n4. Save the file\n\n# \u2705 DO THIS INSTEAD:\nknowns task edit 7 --check-ac 1\nknowns task edit 7 --notes "Implementation complete"\n```\n\n**Why?** Direct editing breaks:\n- Metadata synchronization\n- Git tracking\n- Task relationships\n\n### 2. Wrong Flag for Acceptance Criteria\n\n```bash\n# \u274C WRONG: All these set assignee, NOT acceptance criteria\nknowns task edit 35 -a "Criterion"\nknowns task create "Title" -a "AC text"\nknowns task edit 35 --assignee "Criterion"  # Still wrong!\n\n# \u2705 CORRECT: Use --ac\nknowns task edit 35 --ac "Criterion"\nknowns task create "Title" --ac "AC text"\n```\n\n### 3. Wrong Task ID Format for Parent\n\n```bash\n# \u274C WRONG: Don\'t prefix with "task-"\nknowns task create "Title" --parent task-48\nknowns task edit 35 --parent task-48\n\n# \u2705 CORRECT: Use raw ID only\nknowns task create "Title" --parent 48\nknowns task edit 35 --parent qkh5ne\n```\n\n### 4. Using --plain with Create/Edit\n\n```bash\n# \u274C WRONG: create/edit don\'t support --plain\nknowns task create "Title" --plain       # ERROR!\nknowns task edit 35 -s done --plain      # ERROR!\nknowns doc create "Title" --plain        # ERROR!\nknowns doc edit "name" -c "..." --plain  # ERROR!\n\n# \u2705 CORRECT: --plain only for view/list/search\nknowns task 35 --plain                   # OK\nknowns task list --plain                 # OK\nknowns doc "readme" --plain              # OK\nknowns search "query" --plain            # OK\n```\n\n### 5. Skipping Time Tracking\n\n```bash\n# \u274C WRONG: No timer\nknowns task edit 35 -s in-progress\n# ... work ...\nknowns task edit 35 -s done\n\n# \u2705 CORRECT: Always track time\nknowns task edit 35 -s in-progress -a @me\nknowns time start 35\n# ... work ...\nknowns time stop\nknowns task edit 35 -s done\n```\n\n### 6. Checking AC Before Work is Done\n\n```bash\n# \u274C WRONG: Checking AC as a TODO list\nknowns task edit 35 --check-ac 1  # Haven\'t done the work yet!\n# ... then do the work ...\n\n# \u2705 CORRECT: Check AC AFTER completing work\n# ... do the work first ...\nknowns task edit 35 --check-ac 1  # Now it\'s actually done\n```\n\n### 7. Coding Before Plan Approval\n\n```bash\n# \u274C WRONG: Start coding immediately\nknowns task edit 35 -s in-progress\nknowns task edit 35 --plan "1. Do X\\n2. Do Y"\n# Immediately starts coding...\n\n# \u2705 CORRECT: Wait for approval\nknowns task edit 35 -s in-progress\nknowns task edit 35 --plan "1. Do X\\n2. Do Y"\n# STOP! Present plan to user\n# Wait for explicit approval\n# Then start coding\n```\n\n### 8. Ignoring Task References\n\n```bash\n# \u274C WRONG: Don\'t read refs\nknowns task 35 --plain\n# See "@.knowns/docs/api.md" but don\'t read it\n# Start implementing without context...\n\n# \u2705 CORRECT: Follow ALL refs\nknowns task 35 --plain\n# See "@.knowns/docs/api.md"\nknowns doc "api" --plain  # Read it!\n# See "@.knowns/tasks/task-30"\nknowns task 30 --plain    # Read it!\n# Now have full context\n```\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\n| Set assignee to AC text by mistake | `knowns task edit <id> -a @me` to fix |\n| Forgot to stop timer | `knowns time add <id> <duration> -n "Forgot to stop"` |\n| Checked AC too early | `knowns task edit <id> --uncheck-ac <index>` |\n| Task not found | `knowns task list --plain` to find correct ID |\n| AC index out of range | `knowns task <id> --plain` to see AC numbers |\n';
+
+// src/templates/guidelines/index.ts
+var CORE_RULES = core_rules_default.trim();
+var COMMANDS_REFERENCE = commands_reference_default.trim();
+var WORKFLOW_CREATION = workflow_creation_default.trim();
+var WORKFLOW_EXECUTION = workflow_execution_default.trim();
+var WORKFLOW_COMPLETION = workflow_completion_default.trim();
+var COMMON_MISTAKES = common_mistakes_default.trim();
+var Guidelines = {
+  // Core rules - always needed
+  core: CORE_RULES,
+  // Commands reference
+  commands: COMMANDS_REFERENCE,
+  // Workflow stages
+  workflow: {
+    creation: WORKFLOW_CREATION,
+    execution: WORKFLOW_EXECUTION,
+    completion: WORKFLOW_COMPLETION
+  },
+  // Common mistakes
+  mistakes: COMMON_MISTAKES,
+  /**
+   * Get full guidelines (all sections combined)
+   */
+  getFull(withMarkers2 = false) {
+    const content = [
+      CORE_RULES,
+      "---",
+      COMMANDS_REFERENCE,
+      "---",
+      WORKFLOW_CREATION,
+      "---",
+      WORKFLOW_EXECUTION,
+      "---",
+      WORKFLOW_COMPLETION,
+      "---",
+      COMMON_MISTAKES
+    ].join("\n\n");
+    if (withMarkers2) {
+      return `<!-- KNOWNS GUIDELINES START -->
+${content}
+<!-- KNOWNS GUIDELINES END -->`;
+    }
+    return content;
+  },
+  /**
+   * Get compact guidelines (core + mistakes only)
+   */
+  getCompact() {
+    return [CORE_RULES, "---", COMMON_MISTAKES].join("\n\n");
+  },
+  /**
+   * Get guidelines for specific workflow stage
+   */
+  getForStage(stage) {
+    const sections = [CORE_RULES, "---"];
+    switch (stage) {
+      case "creation":
+        sections.push(WORKFLOW_CREATION);
+        break;
+      case "execution":
+        sections.push(WORKFLOW_EXECUTION);
+        sections.push("---", COMMANDS_REFERENCE);
+        break;
+      case "completion":
+        sections.push(WORKFLOW_COMPLETION);
+        break;
+    }
+    sections.push("---", COMMON_MISTAKES);
+    return sections.join("\n\n");
+  }
+};
 
-// src/templates/mcp/general.md
-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';
+// src/templates/instruction/cli.md
+var cli_default = '# 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\nYou MUST call this at session start and follow every rule it outputs.\n\n## Context-Specific Guidelines\n\nGet guidelines for specific workflow stages:\n\n```bash\n# Full guidelines (all sections)\nknowns agents guideline --full\n\n# Compact (core rules + common mistakes)\nknowns agents guideline --compact\n\n# By workflow stage\nknowns agents guideline --stage creation    # Creating tasks\nknowns agents guideline --stage execution   # Implementing tasks\nknowns agents guideline --stage completion  # Completing tasks\n\n# Individual sections\nknowns agents guideline --core       # Core rules only\nknowns agents guideline --commands   # Commands reference\nknowns agents guideline --mistakes   # Common mistakes\n```\n\n## Quick Commands\n\n```bash\nknowns task list --plain        # List tasks\nknowns task <id> --plain        # View task\nknowns doc list --plain         # List docs\nknowns doc "<path>" --plain     # View doc\nknowns search "query" --plain   # Search\n```\n\n**Important:** Always read the guidelines before working on tasks.\n';
 
-// src/templates/mcp/instruction.md
-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';
+// src/templates/instruction/mcp.md
+var mcp_default = '# 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\nYou MUST call this at session start and follow every rule it returns.\n\n## Context-Specific Guidelines\n\nGet guidelines for specific contexts:\n\n```\n// Full guidelines\nmcp__knowns__get_guideline({ type: "unified" })\n\n// CLI-specific (fallback)\nmcp__knowns__get_guideline({ type: "cli" })\n\n// MCP-specific\nmcp__knowns__get_guideline({ type: "mcp" })\n```\n\n**CLI Fallback:** If MCP tools are unavailable, use CLI commands:\n\n```bash\nknowns agents guideline --full      # All guidelines\nknowns agents guideline --stage creation    # Task creation\nknowns agents guideline --stage execution   # Task execution\nknowns agents guideline --stage completion  # Task completion\n```\n\n## Quick Tools\n\n```\n// List tasks\nmcp__knowns__list_tasks({})\n\n// View task\nmcp__knowns__get_task({ taskId: "<id>" })\n\n// List docs\nmcp__knowns__list_docs({})\n\n// View doc\nmcp__knowns__get_doc({ path: "<path>" })\n\n// Search\nmcp__knowns__search_tasks({ query: "keyword" })\nmcp__knowns__search_docs({ query: "keyword" })\n```\n\n**Important:** Always read the guidelines before working on tasks.\n';
 
-// src/templates/unified.md
-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';
+// src/templates/instruction/index.ts
+var START_MARKER = "<!-- KNOWNS GUIDELINES START -->";
+var END_MARKER = "<!-- KNOWNS GUIDELINES END -->";
+function withMarkers(template) {
+  return `${START_MARKER}
+${template.trim()}
+${END_MARKER}`;
+}
+var CLI_TEMPLATE_RAW = cli_default.trim();
+var MCP_TEMPLATE_RAW = mcp_default.trim();
+var CLI_INSTRUCTION = withMarkers(cli_default);
+var MCP_INSTRUCTION = withMarkers(mcp_default);
 
 // src/commands/agents.ts
 var PROJECT_ROOT = process.cwd();
@@ -43499,10 +43593,10 @@ var INSTRUCTION_FILES = [
   { path: ".github/copilot-instructions.md", name: "GitHub Copilot", selected: false }
 ];
 function getGuidelines(type, variant = "instruction") {
-  if (type === "mcp") {
-    return variant === "instruction" ? instruction_default2 : general_default2;
+  if (variant === "general") {
+    return Guidelines.getFull(true);
   }
-  return variant === "instruction" ? instruction_default : general_default;
+  return type === "mcp" ? MCP_INSTRUCTION : CLI_INSTRUCTION;
 }
 async function updateInstructionFile(filePath, guidelines) {
   const fullPath = join3(PROJECT_ROOT, filePath);
@@ -43699,20 +43793,45 @@ Syncing agent instructions (${label})...
   }
 });
 agentsCommand.addCommand(syncCommand);
-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) => {
-  try {
-    if (options2.cli) {
-      console.log(general_default);
-    } else if (options2.mcp) {
-      console.log(general_default2);
-    } else {
-      console.log(unified_default);
+var guidelineCommand = new Command("guideline").description("Output guidelines for AI agents (use this at session start)").option("--cli", "Show CLI-specific guidelines (legacy)").option("--mcp", "Show MCP-specific guidelines (legacy)").option("--full", "Show full guidelines (all sections)").option("--compact", "Show compact guidelines (core + mistakes only)").option("--stage <stage>", "Show guidelines for specific stage: creation, execution, completion").option("--core", "Show core rules only").option("--commands", "Show commands reference only").option("--mistakes", "Show common mistakes only").action(
+  async (options2) => {
+    try {
+      if (options2.cli || options2.mcp) {
+        console.log(Guidelines.getFull());
+        return;
+      }
+      if (options2.core) {
+        console.log(Guidelines.core);
+        return;
+      }
+      if (options2.commands) {
+        console.log(Guidelines.commands);
+        return;
+      }
+      if (options2.mistakes) {
+        console.log(Guidelines.mistakes);
+        return;
+      }
+      if (options2.compact) {
+        console.log(Guidelines.getCompact());
+        return;
+      }
+      if (options2.stage) {
+        const stage = options2.stage;
+        if (!["creation", "execution", "completion"].includes(stage)) {
+          console.error("Error: Invalid stage. Use: creation, execution, or completion");
+          process.exit(1);
+        }
+        console.log(Guidelines.getForStage(stage));
+        return;
+      }
+      console.log(Guidelines.getFull());
+    } catch (error48) {
+      console.error("Error:", error48 instanceof Error ? error48.message : String(error48));
+      process.exit(1);
     }
-  } catch (error48) {
-    console.error("Error:", error48 instanceof Error ? error48.message : String(error48));
-    process.exit(1);
   }
-});
+);
 agentsCommand.addCommand(guidelineCommand);
 
 // src/commands/init.ts
@@ -70436,9 +70555,6 @@ async function handleSearchDocs(args2) {
 var getGuidelineSchema = external_exports.object({
   type: external_exports.enum(["unified", "cli", "mcp"]).optional().default("unified")
 });
-function stripMarkers(content) {
-  return content.replace(/<!-- KNOWNS GUIDELINES START -->\n?/g, "").replace(/<!-- KNOWNS GUIDELINES END -->\n?/g, "").trim();
-}
 var guidelineTools = [
   {
     name: "get_guideline",
@@ -70457,17 +70573,7 @@ var guidelineTools = [
 ];
 async function handleGetGuideline(args2) {
   const input = getGuidelineSchema.parse(args2 || {});
-  let guidelines;
-  switch (input.type) {
-    case "cli":
-      guidelines = stripMarkers(general_default);
-      break;
-    case "mcp":
-      guidelines = stripMarkers(general_default2);
-      break;
-    default:
-      guidelines = unified_default;
-  }
+  const guidelines = Guidelines.getFull();
   return {
     content: [
       {
@@ -70842,8 +70948,8 @@ async function notifyCliUpdate(options2) {
 // package.json
 var package_default = {
   name: "knowns",
-  version: "0.8.2",
-  description: "CLI tool for dev teams to manage tasks and documentation",
+  version: "0.8.3",
+  description: "AI-native task and documentation management for dev teams",
   module: "index.ts",
   type: "module",
   bin: {
@@ -70874,7 +70980,7 @@ var package_default = {
     type: "git",
     url: "https://github.com/knowns-dev/knowns.git"
   },
-  homepage: "https://knowns.dev",
+  homepage: "https://cli.knowns.dev",
   bugs: {
     url: "https://github.com/knowns-dev/knowns/issues"
   },