@hunghg255/maicli 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/CLAUDE.md +1 -2
  2. package/LICENSE +1 -1
  3. package/dist/index.js +5 -8
  4. package/dist/ui/assets/{index-51RMTjUl.js → index-D4f8U3iQ.js} +69 -69
  5. package/dist/ui/assets/index-gL6jEDe8.css +1 -0
  6. package/dist/ui/index.html +2 -2
  7. package/package.json +1 -1
  8. package/dist/ui/assets/index-BUsOx5xS.css +0 -1
package/CLAUDE.md CHANGED
@@ -875,8 +875,6 @@ maicli doc edit "doc-name" -a "Appended content"
875
875
 
876
876
  ---
877
877
 
878
- **Maintained By**: MAICLI Team
879
-
880
878
  <!-- MAICLI GUIDELINES END -->
881
879
 
882
880
 
@@ -896,3 +894,4 @@ maicli doc edit "doc-name" -a "Appended content"
896
894
 
897
895
 
898
896
 
897
+
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2025 MAICLI Contributors
3
+ Copyright (c) 2025 hunghg255 Contributors
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/dist/index.js CHANGED
@@ -47009,10 +47009,10 @@ var {
47009
47009
  var import_prompts2 = __toESM(require_prompts3(), 1);
47010
47010
 
47011
47011
  // src/templates/maicli-guidelines-cli.md
47012
- var maicli_guidelines_cli_default = '<!-- MAICLI GUIDELINES START -->\n# MAICLI Guidelines\n\n## Core Principles\n\n### 1. CLI-Only Operations\n**NEVER edit .md files directly. ALL operations MUST use CLI commands.**\n\nThis ensures data integrity, maintains proper change history, and prevents file corruption.\n\n### 2. Documentation-First (For AI Agents)\n**ALWAYS read project documentation BEFORE planning or coding.**\n\nAI agents must understand project context, conventions, and existing patterns before making any changes. This prevents rework and ensures consistency.\n\n---\n\n## AI Agent Guidelines\n\n> **CRITICAL**: Before performing ANY task, AI agents MUST read documentation to understand project context.\n\n### First-Time Initialization\n\nWhen starting a new session or working on an unfamiliar project:\n\n```bash\n# 1. List all available documentation\nmaicli doc list --plain\n\n# 2. Read essential project docs (prioritize these)\nmaicli doc "README" --plain # Project overview\nmaicli doc "ARCHITECTURE" --plain # System design\nmaicli doc "CONVENTIONS" --plain # Coding standards\nmaicli doc "API" --plain # API specifications\n\n# 3. Review current task backlog\nmaicli task list --plain\nmaicli task list --status in-progress --plain\n```\n\n### Before Taking Any Task\n\n```bash\n# 1. View the task details\nmaicli task <id> --plain\n\n# 2. Follow ALL refs in the task (see Reference System section)\n# @.maicli/tasks/task-44 - ... \u2192 maicli task 44 --plain\n# @.maicli/docs/patterns/module.md \u2192 maicli doc "patterns/module" --plain\n\n# 3. Search for additional related documentation\nmaicli search "<keywords from task>" --type doc --plain\n\n# 4. Read ALL related docs before planning\nmaicli doc "<related-doc>" --plain\n\n# 5. Check for similar completed tasks (learn from history)\nmaicli search "<keywords>" --type task --status done --plain\n```\n\n### Why Documentation First?\n\n| Without Reading Docs | With Reading Docs |\n|---------------------|-------------------|\n| Reinvent existing patterns | Reuse established patterns |\n| Break conventions | Follow project standards |\n| Duplicate code | Use existing utilities |\n| Wrong architecture decisions | Align with system design |\n| Inconsistent naming | Match naming conventions |\n\n### Context Checklist for Agents\n\nBefore writing ANY code, ensure you can answer:\n\n- [ ] Have I followed ALL refs (`@.maicli/...`) in the task?\n- [ ] Have I followed nested refs recursively?\n- [ ] What is the project\'s overall architecture?\n- [ ] What coding conventions does this project follow?\n- [ ] Are there existing patterns/utilities I should reuse?\n- [ ] What are the testing requirements?\n- [ ] How should I structure my implementation?\n\n> **Remember**: A few minutes reading docs saves hours of rework. NEVER skip this step.\n\n---\n\n## Reference System (Refs)\n\nTasks and docs can contain **references** to other tasks/docs. AI agents MUST understand and follow these refs to gather complete context.\n\n### Reference Formats\n\n| Type | When Writing (Input) | When Reading (Output) | CLI Command |\n|------|---------------------|----------------------|-------------|\n| **Task ref** | `@task-<id>` | `@.maicli/tasks/task-<id> - <title>.md` | `maicli task <id> --plain` |\n| **Doc ref** | `@doc/<path>` | `@.maicli/docs/<path>.md` | `maicli doc <path> --plain` |\n\n> **CRITICAL for AI Agents**:\n> - When **WRITING** refs (in descriptions, plans, notes): Use `@task-<id>` and `@doc/<path>`\n> - When **READING** output from `--plain`: You\'ll see `@.maicli/tasks/...` and `@.maicli/docs/...`\n> - **NEVER write** the output format (`@.maicli/...`) - always use input format (`@task-<id>`, `@doc/<path>`)\n\n### How to Follow Refs\n\nWhen you read a task and see refs in system output format, follow them:\n\n```bash\n# Example: Task 42 output contains:\n# @.maicli/tasks/task-44 - CLI Task Create Command.md\n# @.maicli/docs/patterns/module.md\n\n# Follow task ref (extract ID from task-<id>)\nmaicli task 44 --plain\n\n# Follow doc ref (extract path, remove .md)\nmaicli doc "patterns/module" --plain\n```\n\n### Parsing Rules\n\n1. **Task refs**: `@.maicli/tasks/task-<id> - ...` \u2192 extract `<id>` \u2192 `maicli task <id> --plain`\n2. **Doc refs**: `@.maicli/docs/<path>.md` \u2192 extract `<path>` \u2192 `maicli doc "<path>" --plain`\n\n### Recursive Following\n\nRefs can be nested. Follow until complete context is gathered:\n\n```\nTask 42\n \u2192 @.maicli/docs/README.md\n \u2192 @.maicli/docs/patterns/module.md (found in README)\n \u2192 (read for full pattern details)\n```\n\n### When to Follow Refs\n\n| Situation | Action |\n|-----------|--------|\n| Refs in Description | ALWAYS follow - critical context |\n| Refs in Implementation Plan | Follow if implementing related work |\n| Refs in Notes | Optional - for historical context |\n| Dependency mentions | Follow if marked as blocker |\n\n### Example: Complete Ref Resolution\n\n```bash\n# 1. Read the task\n$ maicli task 42 --plain\n\n# Output contains:\n# @.maicli/tasks/task-44 - CLI Task Create Command.md\n# @.maicli/docs/README.md\n\n# 2. Follow task ref\n$ maicli task 44 --plain\n\n# 3. Follow doc ref\n$ maicli doc "README" --plain\n\n# 4. If README contains more refs, follow them too\n# @.maicli/docs/patterns/module.md \u2192 maicli doc "patterns/module" --plain\n\n# Now you have complete context\n```\n\n> **CRITICAL**: Never assume you understand a task fully without following its refs. Refs contain essential context that may change your implementation approach.\n\n---\n\n## Quick Start\n\n```bash\n# Initialize project\nmaicli init [name]\n\n# Create task with acceptance criteria\nmaicli task create "Title" -d "Description" --ac "Criterion 1" --ac "Criterion 2"\n\n# View task (ALWAYS use --plain for AI)\nmaicli task <id> --plain # Shorthand\nmaicli task view <id> --plain # Full command\n\n# View doc (ALWAYS use --plain for AI)\nmaicli doc <path> --plain # Shorthand\nmaicli doc view "<path>" --plain # Full command\n\n# List tasks\nmaicli task list --plain\n\n# Search (tasks + docs)\nmaicli search "query" --plain\n```\n\n---\n\n## End-to-End Example\n\nHere\'s a complete workflow for an AI agent implementing a feature:\n\n```bash\n# === AGENT SESSION START (Do this once per session) ===\n\n# 0a. List all available documentation\n$ maicli doc list --plain\n\n# Output:\n# DOC: README.md\n# DOC: ARCHITECTURE.md\n# DOC: CONVENTIONS.md\n# DOC: security-patterns.md\n# DOC: api-guidelines.md\n# DOC: email-templates.md\n\n# 0b. Read essential project docs\n$ maicli doc "README" --plain\n$ maicli doc "ARCHITECTURE" --plain\n$ maicli doc "CONVENTIONS" --plain\n\n# Now the agent understands project context and conventions\n\n# === TASK WORKFLOW ===\n\n# 1. Create the task\n$ maicli task create "Add password reset flow" \\\n -d "Users need ability to reset forgotten passwords via email" \\\n --ac "User can request password reset via email" \\\n --ac "Reset link expires after 1 hour" \\\n --ac "User can set new password via reset link" \\\n --ac "Unit tests cover all scenarios" \\\n --priority high \\\n -l "auth,feature"\n\n# Output: Created task AUTH-042\n\n# 2. Take the task and start timer (uses defaultAssignee or @me fallback)\n$ maicli task edit AUTH-042 -s in-progress -a $(maicli config get defaultAssignee --plain || echo "@me")\n$ maicli time start AUTH-042\n\n# Output: Timer started for AUTH-042\n\n# 3. Search for related documentation\n$ maicli search "password security" --type doc --plain\n\n# Output:\n# DOC: security-patterns.md (score: 0.92)\n# DOC: email-templates.md (score: 0.78)\n\n# 4. Read the documentation\n$ maicli doc "security-patterns" --plain\n\n# 5. Create implementation plan (SHARE WITH USER, WAIT FOR APPROVAL)\n$ maicli task edit AUTH-042 --plan $\'1. Review security patterns (see @doc/security-patterns)\n2. Design token generation with 1-hour expiry\n3. Create email template (see @doc/email-templates)\n4. Implement /forgot-password endpoint\n5. Implement /reset-password endpoint\n6. Add unit tests\n7. Update API documentation\'\n\n# 6. After approval, implement and check criteria as you go\n$ maicli task edit AUTH-042 --check-ac 1\n$ maicli task edit AUTH-042 --append-notes "\u2713 Implemented /forgot-password endpoint"\n\n$ maicli task edit AUTH-042 --check-ac 2\n$ maicli task edit AUTH-042 --append-notes "\u2713 Token expiry set to 1 hour"\n\n$ maicli task edit AUTH-042 --check-ac 3\n$ maicli task edit AUTH-042 --append-notes "\u2713 Implemented /reset-password endpoint"\n\n$ maicli task edit AUTH-042 --check-ac 4\n$ maicli task edit AUTH-042 --append-notes "\u2713 Added 12 unit tests, 100% coverage"\n\n# 7. Add final implementation notes\n$ maicli task edit AUTH-042 --notes $\'## Summary\nImplemented complete password reset flow with secure token generation.\n\n## Changes\n- Added POST /forgot-password endpoint\n- Added POST /reset-password endpoint\n- Created password_reset_tokens table\n- Added email template for reset link\n\n## Security\n- Tokens use crypto.randomBytes(32)\n- 1-hour expiry enforced at DB level\n- Rate limiting: 3 requests per hour per email\n\n## Tests\n- 12 unit tests added\n- Coverage: 100% for new code\n\n## Documentation\n- Updated API.md with new endpoints\'\n\n# 8. Stop timer and complete\n$ maicli time stop\n$ maicli task edit AUTH-042 -s done\n\n# Output: Task AUTH-042 marked as done\n```\n\n---\n\n## Task Workflow\n\n### Step 1: Take Task\n\n```bash\n# Assign using defaultAssignee from config (falls back to @me if not set)\nmaicli task edit <id> -s in-progress -a $(maicli config get defaultAssignee --plain || echo "@me")\n```\n\n> **Note**: The `defaultAssignee` is configured in `.maicli/config.json` during `maicli init`. If not set, `@me` is used as fallback. To update: `maicli config set defaultAssignee "@username"`\n\n### Step 2: Start Time Tracking (REQUIRED)\n\n```bash\nmaicli time start <id>\n```\n\n> **CRITICAL**: Time tracking is MANDATORY. Always start timer when taking a task and stop when done. This data is essential for:\n> - Accurate project estimation\n> - Identifying bottlenecks\n> - Resource planning\n> - Sprint retrospectives\n\n### Step 3: Read Related Documentation\n\n> **FOR AI AGENTS**: This step is MANDATORY, not optional. You must understand the codebase before planning.\n\n```bash\n# Search for related docs\nmaicli search "authentication" --type doc --plain\n\n# View relevant documents\nmaicli doc "API Guidelines" --plain\nmaicli doc "Security Patterns" --plain\n\n# Also check for similar completed tasks\nmaicli search "auth" --type task --status done --plain\n```\n\n> **CRITICAL**: ALWAYS read related documentation BEFORE planning! Understanding existing patterns and conventions prevents rework and ensures consistency.\n\n### Step 4: Create Implementation Plan\n\n```bash\nmaicli task edit <id> --plan $\'1. Research patterns (see @doc/security-patterns)\n2. Design middleware\n3. Implement\n4. Add tests\n5. Update docs\'\n```\n\n> **CRITICAL**:\n> - Share plan with user and **WAIT for approval** before coding\n> - Include doc references using `@doc/<path>` format\n\n### Step 5: Implement\n\n```bash\n# Work through implementation plan step by step\n# IMPORTANT: Only check AC AFTER completing the work, not before\n\n# After completing work for AC #1:\nmaicli task edit <id> --check-ac 1\nmaicli task edit <id> --append-notes "\u2713 Completed: <brief description>"\n\n# After completing work for AC #2:\nmaicli task edit <id> --check-ac 2\nmaicli task edit <id> --append-notes "\u2713 Completed: <brief description>"\n```\n\n> **CRITICAL**: Never check an AC before the work is actually done. ACs represent completed outcomes, not intentions.\n\n### Step 6: Handle Dynamic Requests (During Implementation)\n\nIf the user adds new requirements during implementation:\n\n```bash\n# Add new acceptance criteria\nmaicli task edit <id> --ac "New requirement from user"\n\n# Update implementation plan to include new steps\nmaicli task edit <id> --plan $\'1. Original step 1\n2. Original step 2\n3. NEW: Handle user request for X\n4. Continue with remaining work\'\n\n# Append note about scope change\nmaicli task edit <id> --append-notes "\u26A0\uFE0F Scope updated: Added requirement for X per user request"\n\n# Continue with Step 5 (Implement) for new requirements\n```\n\n> **Note**: Always document scope changes. This helps track why a task took longer than expected.\n\n### Step 7: Add Implementation Notes\n\n```bash\n# Add comprehensive notes (suitable for PR description)\nmaicli task edit <id> --notes $\'## Summary\n\nImplemented JWT auth.\n\n## Changes\n- Added middleware\n- Added tests\'\n\n# OR append progressively (recommended)\nmaicli task edit <id> --append-notes "\u2713 Implemented middleware"\nmaicli task edit <id> --append-notes "\u2713 Added tests"\n```\n\n### Step 8: Stop Time Tracking (REQUIRED)\n\n```bash\nmaicli time stop\n```\n\n> **CRITICAL**: Never forget to stop the timer. If you forget, use manual entry: `maicli time add <id> <duration> -n "Forgot to stop timer"`\n\n### Step 9: Complete Task\n\n```bash\nmaicli task edit <id> -s done\n```\n\n### Step 10: Handle Post-Completion Changes (If Applicable)\n\nIf the user requests changes or updates AFTER task is marked done:\n\n```bash\n# 1. Reopen task - set back to in-progress\nmaicli task edit <id> -s in-progress\n\n# 2. Restart time tracking (REQUIRED)\nmaicli time start <id>\n\n# 3. Add new AC for the changes requested\nmaicli task edit <id> --ac "Post-completion fix: <description>"\n\n# 4. Document the reopen reason\nmaicli task edit <id> --append-notes "\u{1F504} Reopened: User requested changes - <reason>"\n\n# 5. Follow Step 5-9 again (Implement \u2192 Notes \u2192 Stop Timer \u2192 Done)\n```\n\n> **CRITICAL**: Treat post-completion changes as a mini-workflow. Always:\n> - Reopen task (in-progress)\n> - Start timer again\n> - Add AC for traceability\n> - Document why it was reopened\n> - Follow the same completion process\n\n### Step 11: Knowledge Extraction (Post-Completion)\n\nAfter completing a task, extract reusable knowledge to docs:\n\n```bash\n# Search if similar pattern already documented\nmaicli search "<pattern/concept>" --type doc --plain\n\n# If new knowledge, create a doc for future reference\nmaicli doc create "Pattern: <Name>" \\\n -d "Reusable pattern discovered during task implementation" \\\n -t "pattern,<domain>" \\\n -f "patterns"\n\n# Or append to existing doc\nmaicli doc edit "<existing-doc>" -a "## New Section\\n\\nLearned from task <id>: ..."\n\n# Reference the source task\nmaicli doc edit "<doc-name>" -a "\\n\\n> Source: @task-<id>"\n```\n\n**When to extract knowledge:**\n- New patterns/conventions discovered\n- Common error solutions\n- Reusable code snippets or approaches\n- Integration patterns with external services\n- Performance optimization techniques\n\n> **CRITICAL**: Only extract **generalizable** knowledge. Task-specific details belong in implementation notes, not docs.\n\n---\n\n## Essential Commands\n\n### Task Management\n\n```bash\n# Create task\nmaicli task create "Title" -d "Description" --ac "Criterion" -l "labels" --priority high\n\n# Edit task\nmaicli task edit <id> -t "New title"\nmaicli task edit <id> -d "New description"\nmaicli task edit <id> -s in-progress\nmaicli task edit <id> --priority high\nmaicli task edit <id> -a <assignee> # $(maicli config get defaultAssignee --plain || echo "@me")\n\n# Acceptance Criteria\nmaicli task edit <id> --ac "New criterion" # Add\nmaicli task edit <id> --check-ac 1 --check-ac 2 # Check (1-indexed)\nmaicli task edit <id> --uncheck-ac 2 # Uncheck\nmaicli task edit <id> --remove-ac 3 # Remove\n\n# Implementation Plan & Notes\nmaicli task edit <id> --plan $\'1. Step\\n2. Step\'\nmaicli task edit <id> --notes "Implementation summary"\nmaicli task edit <id> --append-notes "Progress update"\n\n# View & List\nmaicli task <id> --plain # Shorthand (ALWAYS use --plain)\nmaicli task view <id> --plain # Full command\nmaicli task list --plain\nmaicli task list --status in-progress --plain\nmaicli task list --assignee <assignee> --plain # $(maicli config get defaultAssignee --plain || echo "@me")\nmaicli task list --tree --plain # Tree hierarchy\n```\n\n### Time Tracking\n\n```bash\n# Timer\nmaicli time start <id>\nmaicli time stop\nmaicli time pause\nmaicli time resume\nmaicli time status\n\n# Manual entry\nmaicli time add <id> 2h -n "Note" -d "2025-12-25"\n\n# Reports\nmaicli time report --from "2025-12-01" --to "2025-12-31"\nmaicli time report --by-label --csv > report.csv\n```\n\n### Documentation\n\n```bash\n# List & View\nmaicli doc list --plain\nmaicli doc list --tag architecture --plain\nmaicli doc <path> --plain # Shorthand (ALWAYS use --plain)\nmaicli doc view "<path>" --plain # Full command\n\n# Create (with optional folder)\nmaicli doc create "Title" -d "Description" -t "tags"\nmaicli doc create "Title" -d "Description" -t "tags" -f "folder/path"\n\n# Edit metadata\nmaicli doc edit "Doc Name" -t "New Title" --tags "new,tags"\n\n# Edit content\nmaicli doc edit "Doc Name" -c "New content" # Replace content\nmaicli doc edit "Doc Name" -a "Appended content" # Append to content\n```\n\n### Search\n\n```bash\n# Search everything\nmaicli search "query" --plain\n\n# Search specific type\nmaicli search "auth" --type task --plain\nmaicli search "patterns" --type doc --plain\n\n# Filter\nmaicli search "bug" --status in-progress --priority high --plain\n```\n\n---\n\n## Task Structure\n\n### Title\n\nClear summary (WHAT needs to be done).\n\n| Bad | Good |\n|-----|------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout on slow networks |\n| Update docs | Document rate limiting in API.md |\n\n### Description\n\nExplains WHY and WHAT (not HOW). **Link related docs using `@doc/<path>`**\n\n```markdown\nWe need JWT authentication because sessions don\'t scale for our microservices architecture.\n\nRelated docs: @doc/security-patterns, @doc/api-guidelines\n```\n\n### Acceptance Criteria\n\n**Outcome-oriented**, testable criteria. NOT implementation steps.\n\n| Bad (Implementation details) | Good (Outcomes) |\n|------------------------------|-----------------|\n| Add function handleLogin() in auth.ts | User can login and receive JWT token |\n| Use bcrypt for hashing | Passwords are securely hashed |\n| Add try-catch blocks | Errors return appropriate HTTP status codes |\n\n### Implementation Plan\n\nHOW to solve. Added AFTER taking task, BEFORE coding.\n\n```markdown\n1. Research JWT libraries (see @doc/security-patterns)\n2. Design token structure (access + refresh tokens)\n3. Implement auth middleware\n4. Add unit tests (aim for 90%+ coverage)\n5. Update API.md with new endpoints\n```\n\n### Implementation Notes\n\nSummary for PR description. Added AFTER completion.\n\n```markdown\n## Summary\nImplemented JWT auth using jsonwebtoken library.\n\n## Changes\n- Added auth middleware in src/middleware/auth.ts\n- Added /login and /refresh endpoints\n- Created JWT utility functions\n\n## Tests\n- Added 15 unit tests\n- Coverage: 94%\n\n## Documentation\n- Updated API.md with authentication section\n```\n\n---\n\n## Error Handling\n\n### Common Errors and Solutions\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| `Error: Task not found` | Invalid task ID | Run `maicli task list --plain` to find correct ID |\n| `Error: No active timer` | Calling `time stop` without active timer | Start timer first: `maicli time start <id>` |\n| `Error: Timer already running` | Starting timer when one is active | Stop current: `maicli time stop` |\n| `Error: Invalid status` | Wrong status format | Use lowercase with hyphens: `in-progress`, not `In Progress` |\n| `Error: AC index out of range` | Checking non-existent criterion | View task first: `maicli task <id> --plain` |\n| `Error: Document not found` | Wrong document name | Run `maicli doc list --plain` to find correct name |\n| `Error: Not initialized` | Running commands without init | Run `maicli init` first |\n\n### Debugging Commands\n\n```bash\n# Check CLI version\nmaicli --version\n\n# Verify project is initialized\nmaicli status\n\n# View raw task data (for debugging)\nmaicli task <id> --json\n\n# Check timer status\nmaicli time status\n```\n\n---\n\n## Definition of Done\n\nA task is **Done** ONLY when **ALL** criteria are met:\n\n### Via CLI (Required)\n\n- [ ] All acceptance criteria checked: `--check-ac <index>` (only after work is actually done)\n- [ ] Implementation notes added: `--notes "..."`\n- [ ] \u23F1\uFE0F Timer stopped: `maicli time stop` (MANDATORY - do not skip!)\n- [ ] Status set to done: `-s done`\n- [ ] Knowledge extracted to docs (if applicable)\n\n### Via Code (Required)\n\n- [ ] All tests pass\n- [ ] Documentation updated\n- [ ] Code reviewed (linting, formatting)\n- [ ] No regressions introduced\n\n---\n\n## Status & Priority Reference\n\n### Status Values\n\nUse **lowercase with hyphens**:\n\n| Status | Description | When to Use |\n|--------|-------------|-------------|\n| `todo` | Not started | Default for new tasks |\n| `in-progress` | Currently working | After taking task |\n| `in-review` | In code review | PR submitted |\n| `blocked` | Waiting on dependency | External blocker |\n| `done` | Completed | All criteria met |\n\n### Priority Values\n\n| Priority | Description |\n|----------|-------------|\n| `low` | Can wait, nice-to-have |\n| `medium` | Normal priority (default) |\n| `high` | Urgent, time-sensitive |\n\n---\n\n## Common Mistakes\n\n| Wrong | Right |\n|-------|-------|\n| Edit .md files directly | Use `maicli task edit` |\n| Change `- [ ]` to `- [x]` in file | Use `--check-ac <index>` |\n| Check AC before completing work | Only check AC AFTER work is actually done |\n| Skip time tracking | ALWAYS use `time start` and `time stop` |\n| Start coding without reading docs | Read ALL related docs FIRST |\n| Skip `maicli doc list` on new project | Always list docs when starting |\n| Assume you know the conventions | Read CONVENTIONS/ARCHITECTURE docs |\n| Plan without checking docs | Read docs before planning |\n| Ignore similar completed tasks | Search done tasks for patterns |\n| Missing doc links in description/plan | Link docs using `@doc/<path>` |\n| Write refs as `@.maicli/docs/...` or `@.maicli/tasks/...` | Use input format: `@doc/<path>`, `@task-<id>` |\n| Forget `--plain` flag | Always use `--plain` for AI |\n| Code before plan approval | Share plan, WAIT for approval |\n| Mark done without all criteria | Check ALL criteria first |\n| Write implementation steps in AC | Write outcome-oriented criteria |\n| Use `"In Progress"` or `"Done"` | Use `in-progress`, `done` |\n| Use `@yourself` or unknown assignee | Use `$(maicli config get defaultAssignee --plain \\|\\| echo "@me")` |\n| Ignore refs in task description | Follow ALL refs (`@.maicli/...`) before planning |\n| See `@.maicli/docs/...` but don\'t read | Use `maicli doc "<path>" --plain` |\n| See `@.maicli/tasks/task-X` but don\'t check | Use `maicli task X --plain` for context |\n| Follow only first-level refs | Recursively follow nested refs until complete |\n\n---\n\n## Platform-Specific Notes\n\n### Multi-line Input\n\nDifferent shells handle multi-line strings differently:\n\n**Bash / Zsh (Recommended)**\n```bash\nmaicli task edit <id> --plan $\'1. First step\\n2. Second step\\n3. Third step\'\n```\n\n**PowerShell**\n```powershell\nmaicli task edit <id> --plan "1. First step`n2. Second step`n3. Third step"\n```\n\n**Cross-platform (Using printf)**\n```bash\nmaicli task edit <id> --plan "$(printf \'1. First step\\n2. Second step\\n3. Third step\')"\n```\n\n**Using heredoc (for long content)**\n```bash\nmaicli task edit <id> --plan "$(cat <<EOF\n1. First step\n2. Second step\n3. Third step\nEOF\n)"\n```\n\n### Path Separators\n\n- **Unix/macOS**: Use forward slashes: `./docs/api.md`\n- **Windows**: Both work, but prefer forward slashes for consistency\n\n---\n\n## Best Practices Checklist\n\n### For AI Agents: Session Start\n\n- [ ] List all docs: `maicli doc list --plain`\n- [ ] Read README/ARCHITECTURE docs\n- [ ] Understand coding conventions\n- [ ] Review current task backlog\n\n### Before Starting Work\n\n- [ ] Task has clear acceptance criteria\n- [ ] ALL refs in task followed (`@.maicli/...`)\n- [ ] Nested refs recursively followed until complete context gathered\n- [ ] Related docs searched: `maicli search "keyword" --type doc --plain`\n- [ ] ALL relevant docs read: `maicli doc "Doc Name" --plain`\n- [ ] Similar done tasks reviewed for patterns\n- [ ] Task assigned to self: `-a $(maicli config get defaultAssignee --plain || echo "@me")`\n- [ ] Status set to in-progress: `-s in-progress`\n- [ ] Timer started: `maicli time start <id>`\n\n### During Work\n\n- [ ] Implementation plan created and approved\n- [ ] Doc links included in plan: `@doc/<path>`\n- [ ] Criteria checked as completed: `--check-ac <index>`\n- [ ] Progress notes appended: `--append-notes "\u2713 ..."`\n\n### After Work\n\n- [ ] All acceptance criteria checked (only after work is done)\n- [ ] Implementation notes added: `--notes "..."`\n- [ ] Timer stopped: `maicli time stop`\n- [ ] Tests passing\n- [ ] Documentation updated\n- [ ] Status set to done: `-s done`\n- [ ] Knowledge extracted to docs (if applicable): patterns, solutions, conventions\n\n---\n\n## Quick Reference Card\n\n```bash\n# === AGENT INITIALIZATION (Once per session) ===\nmaicli doc list --plain\nmaicli doc "README" --plain\nmaicli doc "ARCHITECTURE" --plain\nmaicli doc "CONVENTIONS" --plain\n\n# === FULL WORKFLOW ===\nmaicli task create "Title" -d "Description" --ac "Criterion"\nmaicli task edit <id> -s in-progress -a $(maicli config get defaultAssignee --plain || echo "@me")\nmaicli time start <id> # \u23F1\uFE0F REQUIRED: Start timer\nmaicli search "keyword" --type doc --plain\nmaicli doc "Doc Name" --plain\nmaicli search "keyword" --type task --status done --plain # Learn from history\nmaicli task edit <id> --plan $\'1. Step (see @doc/file)\\n2. Step\'\n# ... wait for approval, then implement ...\n# Only check AC AFTER completing the work:\nmaicli task edit <id> --check-ac 1\nmaicli task edit <id> --append-notes "\u2713 Completed: feature X"\nmaicli task edit <id> --check-ac 2\nmaicli task edit <id> --append-notes "\u2713 Completed: feature Y"\nmaicli time stop # \u23F1\uFE0F REQUIRED: Stop timer\nmaicli task edit <id> -s done\n# Optional: Extract knowledge to docs if generalizable patterns found\n\n# === VIEW & SEARCH ===\nmaicli task <id> --plain # Shorthand for view\nmaicli task list --plain\nmaicli task list --status in-progress --assignee $(maicli config get defaultAssignee --plain || echo "@me") --plain\nmaicli search "query" --plain\nmaicli search "bug" --type task --status in-progress --plain\n\n# === TIME TRACKING ===\nmaicli time start <id>\nmaicli time stop\nmaicli time status\nmaicli time report --from "2025-12-01" --to "2025-12-31"\n\n# === DOCUMENTATION ===\nmaicli doc list --plain\nmaicli doc "path/doc-name" --plain # Shorthand for view\nmaicli doc create "Title" -d "Description" -t "tags" -f "folder"\nmaicli doc edit "doc-name" -c "New content"\nmaicli doc edit "doc-name" -a "Appended content"\n```\n\n---\n\n**Maintained By**: MAICLI Team\n\n<!-- MAICLI GUIDELINES END -->\n';
47012
+ var maicli_guidelines_cli_default = '<!-- MAICLI GUIDELINES START -->\n# MAICLI Guidelines\n\n## Core Principles\n\n### 1. CLI-Only Operations\n**NEVER edit .md files directly. ALL operations MUST use CLI commands.**\n\nThis ensures data integrity, maintains proper change history, and prevents file corruption.\n\n### 2. Documentation-First (For AI Agents)\n**ALWAYS read project documentation BEFORE planning or coding.**\n\nAI agents must understand project context, conventions, and existing patterns before making any changes. This prevents rework and ensures consistency.\n\n---\n\n## AI Agent Guidelines\n\n> **CRITICAL**: Before performing ANY task, AI agents MUST read documentation to understand project context.\n\n### First-Time Initialization\n\nWhen starting a new session or working on an unfamiliar project:\n\n```bash\n# 1. List all available documentation\nmaicli doc list --plain\n\n# 2. Read essential project docs (prioritize these)\nmaicli doc "README" --plain # Project overview\nmaicli doc "ARCHITECTURE" --plain # System design\nmaicli doc "CONVENTIONS" --plain # Coding standards\nmaicli doc "API" --plain # API specifications\n\n# 3. Review current task backlog\nmaicli task list --plain\nmaicli task list --status in-progress --plain\n```\n\n### Before Taking Any Task\n\n```bash\n# 1. View the task details\nmaicli task <id> --plain\n\n# 2. Follow ALL refs in the task (see Reference System section)\n# @.maicli/tasks/task-44 - ... \u2192 maicli task 44 --plain\n# @.maicli/docs/patterns/module.md \u2192 maicli doc "patterns/module" --plain\n\n# 3. Search for additional related documentation\nmaicli search "<keywords from task>" --type doc --plain\n\n# 4. Read ALL related docs before planning\nmaicli doc "<related-doc>" --plain\n\n# 5. Check for similar completed tasks (learn from history)\nmaicli search "<keywords>" --type task --status done --plain\n```\n\n### Why Documentation First?\n\n| Without Reading Docs | With Reading Docs |\n|---------------------|-------------------|\n| Reinvent existing patterns | Reuse established patterns |\n| Break conventions | Follow project standards |\n| Duplicate code | Use existing utilities |\n| Wrong architecture decisions | Align with system design |\n| Inconsistent naming | Match naming conventions |\n\n### Context Checklist for Agents\n\nBefore writing ANY code, ensure you can answer:\n\n- [ ] Have I followed ALL refs (`@.maicli/...`) in the task?\n- [ ] Have I followed nested refs recursively?\n- [ ] What is the project\'s overall architecture?\n- [ ] What coding conventions does this project follow?\n- [ ] Are there existing patterns/utilities I should reuse?\n- [ ] What are the testing requirements?\n- [ ] How should I structure my implementation?\n\n> **Remember**: A few minutes reading docs saves hours of rework. NEVER skip this step.\n\n---\n\n## Reference System (Refs)\n\nTasks and docs can contain **references** to other tasks/docs. AI agents MUST understand and follow these refs to gather complete context.\n\n### Reference Formats\n\n| Type | When Writing (Input) | When Reading (Output) | CLI Command |\n|------|---------------------|----------------------|-------------|\n| **Task ref** | `@task-<id>` | `@.maicli/tasks/task-<id> - <title>.md` | `maicli task <id> --plain` |\n| **Doc ref** | `@doc/<path>` | `@.maicli/docs/<path>.md` | `maicli doc <path> --plain` |\n\n> **CRITICAL for AI Agents**:\n> - When **WRITING** refs (in descriptions, plans, notes): Use `@task-<id>` and `@doc/<path>`\n> - When **READING** output from `--plain`: You\'ll see `@.maicli/tasks/...` and `@.maicli/docs/...`\n> - **NEVER write** the output format (`@.maicli/...`) - always use input format (`@task-<id>`, `@doc/<path>`)\n\n### How to Follow Refs\n\nWhen you read a task and see refs in system output format, follow them:\n\n```bash\n# Example: Task 42 output contains:\n# @.maicli/tasks/task-44 - CLI Task Create Command.md\n# @.maicli/docs/patterns/module.md\n\n# Follow task ref (extract ID from task-<id>)\nmaicli task 44 --plain\n\n# Follow doc ref (extract path, remove .md)\nmaicli doc "patterns/module" --plain\n```\n\n### Parsing Rules\n\n1. **Task refs**: `@.maicli/tasks/task-<id> - ...` \u2192 extract `<id>` \u2192 `maicli task <id> --plain`\n2. **Doc refs**: `@.maicli/docs/<path>.md` \u2192 extract `<path>` \u2192 `maicli doc "<path>" --plain`\n\n### Recursive Following\n\nRefs can be nested. Follow until complete context is gathered:\n\n```\nTask 42\n \u2192 @.maicli/docs/README.md\n \u2192 @.maicli/docs/patterns/module.md (found in README)\n \u2192 (read for full pattern details)\n```\n\n### When to Follow Refs\n\n| Situation | Action |\n|-----------|--------|\n| Refs in Description | ALWAYS follow - critical context |\n| Refs in Implementation Plan | Follow if implementing related work |\n| Refs in Notes | Optional - for historical context |\n| Dependency mentions | Follow if marked as blocker |\n\n### Example: Complete Ref Resolution\n\n```bash\n# 1. Read the task\n$ maicli task 42 --plain\n\n# Output contains:\n# @.maicli/tasks/task-44 - CLI Task Create Command.md\n# @.maicli/docs/README.md\n\n# 2. Follow task ref\n$ maicli task 44 --plain\n\n# 3. Follow doc ref\n$ maicli doc "README" --plain\n\n# 4. If README contains more refs, follow them too\n# @.maicli/docs/patterns/module.md \u2192 maicli doc "patterns/module" --plain\n\n# Now you have complete context\n```\n\n> **CRITICAL**: Never assume you understand a task fully without following its refs. Refs contain essential context that may change your implementation approach.\n\n---\n\n## Quick Start\n\n```bash\n# Initialize project\nmaicli init [name]\n\n# Create task with acceptance criteria\nmaicli task create "Title" -d "Description" --ac "Criterion 1" --ac "Criterion 2"\n\n# View task (ALWAYS use --plain for AI)\nmaicli task <id> --plain # Shorthand\nmaicli task view <id> --plain # Full command\n\n# View doc (ALWAYS use --plain for AI)\nmaicli doc <path> --plain # Shorthand\nmaicli doc view "<path>" --plain # Full command\n\n# List tasks\nmaicli task list --plain\n\n# Search (tasks + docs)\nmaicli search "query" --plain\n```\n\n---\n\n## End-to-End Example\n\nHere\'s a complete workflow for an AI agent implementing a feature:\n\n```bash\n# === AGENT SESSION START (Do this once per session) ===\n\n# 0a. List all available documentation\n$ maicli doc list --plain\n\n# Output:\n# DOC: README.md\n# DOC: ARCHITECTURE.md\n# DOC: CONVENTIONS.md\n# DOC: security-patterns.md\n# DOC: api-guidelines.md\n# DOC: email-templates.md\n\n# 0b. Read essential project docs\n$ maicli doc "README" --plain\n$ maicli doc "ARCHITECTURE" --plain\n$ maicli doc "CONVENTIONS" --plain\n\n# Now the agent understands project context and conventions\n\n# === TASK WORKFLOW ===\n\n# 1. Create the task\n$ maicli task create "Add password reset flow" \\\n -d "Users need ability to reset forgotten passwords via email" \\\n --ac "User can request password reset via email" \\\n --ac "Reset link expires after 1 hour" \\\n --ac "User can set new password via reset link" \\\n --ac "Unit tests cover all scenarios" \\\n --priority high \\\n -l "auth,feature"\n\n# Output: Created task AUTH-042\n\n# 2. Take the task and start timer (uses defaultAssignee or @me fallback)\n$ maicli task edit AUTH-042 -s in-progress -a $(maicli config get defaultAssignee --plain || echo "@me")\n$ maicli time start AUTH-042\n\n# Output: Timer started for AUTH-042\n\n# 3. Search for related documentation\n$ maicli search "password security" --type doc --plain\n\n# Output:\n# DOC: security-patterns.md (score: 0.92)\n# DOC: email-templates.md (score: 0.78)\n\n# 4. Read the documentation\n$ maicli doc "security-patterns" --plain\n\n# 5. Create implementation plan (SHARE WITH USER, WAIT FOR APPROVAL)\n$ maicli task edit AUTH-042 --plan $\'1. Review security patterns (see @doc/security-patterns)\n2. Design token generation with 1-hour expiry\n3. Create email template (see @doc/email-templates)\n4. Implement /forgot-password endpoint\n5. Implement /reset-password endpoint\n6. Add unit tests\n7. Update API documentation\'\n\n# 6. After approval, implement and check criteria as you go\n$ maicli task edit AUTH-042 --check-ac 1\n$ maicli task edit AUTH-042 --append-notes "\u2713 Implemented /forgot-password endpoint"\n\n$ maicli task edit AUTH-042 --check-ac 2\n$ maicli task edit AUTH-042 --append-notes "\u2713 Token expiry set to 1 hour"\n\n$ maicli task edit AUTH-042 --check-ac 3\n$ maicli task edit AUTH-042 --append-notes "\u2713 Implemented /reset-password endpoint"\n\n$ maicli task edit AUTH-042 --check-ac 4\n$ maicli task edit AUTH-042 --append-notes "\u2713 Added 12 unit tests, 100% coverage"\n\n# 7. Add final implementation notes\n$ maicli task edit AUTH-042 --notes $\'## Summary\nImplemented complete password reset flow with secure token generation.\n\n## Changes\n- Added POST /forgot-password endpoint\n- Added POST /reset-password endpoint\n- Created password_reset_tokens table\n- Added email template for reset link\n\n## Security\n- Tokens use crypto.randomBytes(32)\n- 1-hour expiry enforced at DB level\n- Rate limiting: 3 requests per hour per email\n\n## Tests\n- 12 unit tests added\n- Coverage: 100% for new code\n\n## Documentation\n- Updated API.md with new endpoints\'\n\n# 8. Stop timer and complete\n$ maicli time stop\n$ maicli task edit AUTH-042 -s done\n\n# Output: Task AUTH-042 marked as done\n```\n\n---\n\n## Task Workflow\n\n### Step 1: Take Task\n\n```bash\n# Assign using defaultAssignee from config (falls back to @me if not set)\nmaicli task edit <id> -s in-progress -a $(maicli config get defaultAssignee --plain || echo "@me")\n```\n\n> **Note**: The `defaultAssignee` is configured in `.maicli/config.json` during `maicli init`. If not set, `@me` is used as fallback. To update: `maicli config set defaultAssignee "@username"`\n\n### Step 2: Start Time Tracking (REQUIRED)\n\n```bash\nmaicli time start <id>\n```\n\n> **CRITICAL**: Time tracking is MANDATORY. Always start timer when taking a task and stop when done. This data is essential for:\n> - Accurate project estimation\n> - Identifying bottlenecks\n> - Resource planning\n> - Sprint retrospectives\n\n### Step 3: Read Related Documentation\n\n> **FOR AI AGENTS**: This step is MANDATORY, not optional. You must understand the codebase before planning.\n\n```bash\n# Search for related docs\nmaicli search "authentication" --type doc --plain\n\n# View relevant documents\nmaicli doc "API Guidelines" --plain\nmaicli doc "Security Patterns" --plain\n\n# Also check for similar completed tasks\nmaicli search "auth" --type task --status done --plain\n```\n\n> **CRITICAL**: ALWAYS read related documentation BEFORE planning! Understanding existing patterns and conventions prevents rework and ensures consistency.\n\n### Step 4: Create Implementation Plan\n\n```bash\nmaicli task edit <id> --plan $\'1. Research patterns (see @doc/security-patterns)\n2. Design middleware\n3. Implement\n4. Add tests\n5. Update docs\'\n```\n\n> **CRITICAL**:\n> - Share plan with user and **WAIT for approval** before coding\n> - Include doc references using `@doc/<path>` format\n\n### Step 5: Implement\n\n```bash\n# Work through implementation plan step by step\n# IMPORTANT: Only check AC AFTER completing the work, not before\n\n# After completing work for AC #1:\nmaicli task edit <id> --check-ac 1\nmaicli task edit <id> --append-notes "\u2713 Completed: <brief description>"\n\n# After completing work for AC #2:\nmaicli task edit <id> --check-ac 2\nmaicli task edit <id> --append-notes "\u2713 Completed: <brief description>"\n```\n\n> **CRITICAL**: Never check an AC before the work is actually done. ACs represent completed outcomes, not intentions.\n\n### Step 6: Handle Dynamic Requests (During Implementation)\n\nIf the user adds new requirements during implementation:\n\n```bash\n# Add new acceptance criteria\nmaicli task edit <id> --ac "New requirement from user"\n\n# Update implementation plan to include new steps\nmaicli task edit <id> --plan $\'1. Original step 1\n2. Original step 2\n3. NEW: Handle user request for X\n4. Continue with remaining work\'\n\n# Append note about scope change\nmaicli task edit <id> --append-notes "\u26A0\uFE0F Scope updated: Added requirement for X per user request"\n\n# Continue with Step 5 (Implement) for new requirements\n```\n\n> **Note**: Always document scope changes. This helps track why a task took longer than expected.\n\n### Step 7: Add Implementation Notes\n\n```bash\n# Add comprehensive notes (suitable for PR description)\nmaicli task edit <id> --notes $\'## Summary\n\nImplemented JWT auth.\n\n## Changes\n- Added middleware\n- Added tests\'\n\n# OR append progressively (recommended)\nmaicli task edit <id> --append-notes "\u2713 Implemented middleware"\nmaicli task edit <id> --append-notes "\u2713 Added tests"\n```\n\n### Step 8: Stop Time Tracking (REQUIRED)\n\n```bash\nmaicli time stop\n```\n\n> **CRITICAL**: Never forget to stop the timer. If you forget, use manual entry: `maicli time add <id> <duration> -n "Forgot to stop timer"`\n\n### Step 9: Complete Task\n\n```bash\nmaicli task edit <id> -s done\n```\n\n### Step 10: Handle Post-Completion Changes (If Applicable)\n\nIf the user requests changes or updates AFTER task is marked done:\n\n```bash\n# 1. Reopen task - set back to in-progress\nmaicli task edit <id> -s in-progress\n\n# 2. Restart time tracking (REQUIRED)\nmaicli time start <id>\n\n# 3. Add new AC for the changes requested\nmaicli task edit <id> --ac "Post-completion fix: <description>"\n\n# 4. Document the reopen reason\nmaicli task edit <id> --append-notes "\u{1F504} Reopened: User requested changes - <reason>"\n\n# 5. Follow Step 5-9 again (Implement \u2192 Notes \u2192 Stop Timer \u2192 Done)\n```\n\n> **CRITICAL**: Treat post-completion changes as a mini-workflow. Always:\n> - Reopen task (in-progress)\n> - Start timer again\n> - Add AC for traceability\n> - Document why it was reopened\n> - Follow the same completion process\n\n### Step 11: Knowledge Extraction (Post-Completion)\n\nAfter completing a task, extract reusable knowledge to docs:\n\n```bash\n# Search if similar pattern already documented\nmaicli search "<pattern/concept>" --type doc --plain\n\n# If new knowledge, create a doc for future reference\nmaicli doc create "Pattern: <Name>" \\\n -d "Reusable pattern discovered during task implementation" \\\n -t "pattern,<domain>" \\\n -f "patterns"\n\n# Or append to existing doc\nmaicli doc edit "<existing-doc>" -a "## New Section\\n\\nLearned from task <id>: ..."\n\n# Reference the source task\nmaicli doc edit "<doc-name>" -a "\\n\\n> Source: @task-<id>"\n```\n\n**When to extract knowledge:**\n- New patterns/conventions discovered\n- Common error solutions\n- Reusable code snippets or approaches\n- Integration patterns with external services\n- Performance optimization techniques\n\n> **CRITICAL**: Only extract **generalizable** knowledge. Task-specific details belong in implementation notes, not docs.\n\n---\n\n## Essential Commands\n\n### Task Management\n\n```bash\n# Create task\nmaicli task create "Title" -d "Description" --ac "Criterion" -l "labels" --priority high\n\n# Edit task\nmaicli task edit <id> -t "New title"\nmaicli task edit <id> -d "New description"\nmaicli task edit <id> -s in-progress\nmaicli task edit <id> --priority high\nmaicli task edit <id> -a <assignee> # $(maicli config get defaultAssignee --plain || echo "@me")\n\n# Acceptance Criteria\nmaicli task edit <id> --ac "New criterion" # Add\nmaicli task edit <id> --check-ac 1 --check-ac 2 # Check (1-indexed)\nmaicli task edit <id> --uncheck-ac 2 # Uncheck\nmaicli task edit <id> --remove-ac 3 # Remove\n\n# Implementation Plan & Notes\nmaicli task edit <id> --plan $\'1. Step\\n2. Step\'\nmaicli task edit <id> --notes "Implementation summary"\nmaicli task edit <id> --append-notes "Progress update"\n\n# View & List\nmaicli task <id> --plain # Shorthand (ALWAYS use --plain)\nmaicli task view <id> --plain # Full command\nmaicli task list --plain\nmaicli task list --status in-progress --plain\nmaicli task list --assignee <assignee> --plain # $(maicli config get defaultAssignee --plain || echo "@me")\nmaicli task list --tree --plain # Tree hierarchy\n```\n\n### Time Tracking\n\n```bash\n# Timer\nmaicli time start <id>\nmaicli time stop\nmaicli time pause\nmaicli time resume\nmaicli time status\n\n# Manual entry\nmaicli time add <id> 2h -n "Note" -d "2025-12-25"\n\n# Reports\nmaicli time report --from "2025-12-01" --to "2025-12-31"\nmaicli time report --by-label --csv > report.csv\n```\n\n### Documentation\n\n```bash\n# List & View\nmaicli doc list --plain\nmaicli doc list --tag architecture --plain\nmaicli doc <path> --plain # Shorthand (ALWAYS use --plain)\nmaicli doc view "<path>" --plain # Full command\n\n# Create (with optional folder)\nmaicli doc create "Title" -d "Description" -t "tags"\nmaicli doc create "Title" -d "Description" -t "tags" -f "folder/path"\n\n# Edit metadata\nmaicli doc edit "Doc Name" -t "New Title" --tags "new,tags"\n\n# Edit content\nmaicli doc edit "Doc Name" -c "New content" # Replace content\nmaicli doc edit "Doc Name" -a "Appended content" # Append to content\n```\n\n### Search\n\n```bash\n# Search everything\nmaicli search "query" --plain\n\n# Search specific type\nmaicli search "auth" --type task --plain\nmaicli search "patterns" --type doc --plain\n\n# Filter\nmaicli search "bug" --status in-progress --priority high --plain\n```\n\n---\n\n## Task Structure\n\n### Title\n\nClear summary (WHAT needs to be done).\n\n| Bad | Good |\n|-----|------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout on slow networks |\n| Update docs | Document rate limiting in API.md |\n\n### Description\n\nExplains WHY and WHAT (not HOW). **Link related docs using `@doc/<path>`**\n\n```markdown\nWe need JWT authentication because sessions don\'t scale for our microservices architecture.\n\nRelated docs: @doc/security-patterns, @doc/api-guidelines\n```\n\n### Acceptance Criteria\n\n**Outcome-oriented**, testable criteria. NOT implementation steps.\n\n| Bad (Implementation details) | Good (Outcomes) |\n|------------------------------|-----------------|\n| Add function handleLogin() in auth.ts | User can login and receive JWT token |\n| Use bcrypt for hashing | Passwords are securely hashed |\n| Add try-catch blocks | Errors return appropriate HTTP status codes |\n\n### Implementation Plan\n\nHOW to solve. Added AFTER taking task, BEFORE coding.\n\n```markdown\n1. Research JWT libraries (see @doc/security-patterns)\n2. Design token structure (access + refresh tokens)\n3. Implement auth middleware\n4. Add unit tests (aim for 90%+ coverage)\n5. Update API.md with new endpoints\n```\n\n### Implementation Notes\n\nSummary for PR description. Added AFTER completion.\n\n```markdown\n## Summary\nImplemented JWT auth using jsonwebtoken library.\n\n## Changes\n- Added auth middleware in src/middleware/auth.ts\n- Added /login and /refresh endpoints\n- Created JWT utility functions\n\n## Tests\n- Added 15 unit tests\n- Coverage: 94%\n\n## Documentation\n- Updated API.md with authentication section\n```\n\n---\n\n## Error Handling\n\n### Common Errors and Solutions\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| `Error: Task not found` | Invalid task ID | Run `maicli task list --plain` to find correct ID |\n| `Error: No active timer` | Calling `time stop` without active timer | Start timer first: `maicli time start <id>` |\n| `Error: Timer already running` | Starting timer when one is active | Stop current: `maicli time stop` |\n| `Error: Invalid status` | Wrong status format | Use lowercase with hyphens: `in-progress`, not `In Progress` |\n| `Error: AC index out of range` | Checking non-existent criterion | View task first: `maicli task <id> --plain` |\n| `Error: Document not found` | Wrong document name | Run `maicli doc list --plain` to find correct name |\n| `Error: Not initialized` | Running commands without init | Run `maicli init` first |\n\n### Debugging Commands\n\n```bash\n# Check CLI version\nmaicli --version\n\n# Verify project is initialized\nmaicli status\n\n# View raw task data (for debugging)\nmaicli task <id> --json\n\n# Check timer status\nmaicli time status\n```\n\n---\n\n## Definition of Done\n\nA task is **Done** ONLY when **ALL** criteria are met:\n\n### Via CLI (Required)\n\n- [ ] All acceptance criteria checked: `--check-ac <index>` (only after work is actually done)\n- [ ] Implementation notes added: `--notes "..."`\n- [ ] \u23F1\uFE0F Timer stopped: `maicli time stop` (MANDATORY - do not skip!)\n- [ ] Status set to done: `-s done`\n- [ ] Knowledge extracted to docs (if applicable)\n\n### Via Code (Required)\n\n- [ ] All tests pass\n- [ ] Documentation updated\n- [ ] Code reviewed (linting, formatting)\n- [ ] No regressions introduced\n\n---\n\n## Status & Priority Reference\n\n### Status Values\n\nUse **lowercase with hyphens**:\n\n| Status | Description | When to Use |\n|--------|-------------|-------------|\n| `todo` | Not started | Default for new tasks |\n| `in-progress` | Currently working | After taking task |\n| `in-review` | In code review | PR submitted |\n| `blocked` | Waiting on dependency | External blocker |\n| `done` | Completed | All criteria met |\n\n### Priority Values\n\n| Priority | Description |\n|----------|-------------|\n| `low` | Can wait, nice-to-have |\n| `medium` | Normal priority (default) |\n| `high` | Urgent, time-sensitive |\n\n---\n\n## Common Mistakes\n\n| Wrong | Right |\n|-------|-------|\n| Edit .md files directly | Use `maicli task edit` |\n| Change `- [ ]` to `- [x]` in file | Use `--check-ac <index>` |\n| Check AC before completing work | Only check AC AFTER work is actually done |\n| Skip time tracking | ALWAYS use `time start` and `time stop` |\n| Start coding without reading docs | Read ALL related docs FIRST |\n| Skip `maicli doc list` on new project | Always list docs when starting |\n| Assume you know the conventions | Read CONVENTIONS/ARCHITECTURE docs |\n| Plan without checking docs | Read docs before planning |\n| Ignore similar completed tasks | Search done tasks for patterns |\n| Missing doc links in description/plan | Link docs using `@doc/<path>` |\n| Write refs as `@.maicli/docs/...` or `@.maicli/tasks/...` | Use input format: `@doc/<path>`, `@task-<id>` |\n| Forget `--plain` flag | Always use `--plain` for AI |\n| Code before plan approval | Share plan, WAIT for approval |\n| Mark done without all criteria | Check ALL criteria first |\n| Write implementation steps in AC | Write outcome-oriented criteria |\n| Use `"In Progress"` or `"Done"` | Use `in-progress`, `done` |\n| Use `@yourself` or unknown assignee | Use `$(maicli config get defaultAssignee --plain \\|\\| echo "@me")` |\n| Ignore refs in task description | Follow ALL refs (`@.maicli/...`) before planning |\n| See `@.maicli/docs/...` but don\'t read | Use `maicli doc "<path>" --plain` |\n| See `@.maicli/tasks/task-X` but don\'t check | Use `maicli task X --plain` for context |\n| Follow only first-level refs | Recursively follow nested refs until complete |\n\n---\n\n## Platform-Specific Notes\n\n### Multi-line Input\n\nDifferent shells handle multi-line strings differently:\n\n**Bash / Zsh (Recommended)**\n```bash\nmaicli task edit <id> --plan $\'1. First step\\n2. Second step\\n3. Third step\'\n```\n\n**PowerShell**\n```powershell\nmaicli task edit <id> --plan "1. First step`n2. Second step`n3. Third step"\n```\n\n**Cross-platform (Using printf)**\n```bash\nmaicli task edit <id> --plan "$(printf \'1. First step\\n2. Second step\\n3. Third step\')"\n```\n\n**Using heredoc (for long content)**\n```bash\nmaicli task edit <id> --plan "$(cat <<EOF\n1. First step\n2. Second step\n3. Third step\nEOF\n)"\n```\n\n### Path Separators\n\n- **Unix/macOS**: Use forward slashes: `./docs/api.md`\n- **Windows**: Both work, but prefer forward slashes for consistency\n\n---\n\n## Best Practices Checklist\n\n### For AI Agents: Session Start\n\n- [ ] List all docs: `maicli doc list --plain`\n- [ ] Read README/ARCHITECTURE docs\n- [ ] Understand coding conventions\n- [ ] Review current task backlog\n\n### Before Starting Work\n\n- [ ] Task has clear acceptance criteria\n- [ ] ALL refs in task followed (`@.maicli/...`)\n- [ ] Nested refs recursively followed until complete context gathered\n- [ ] Related docs searched: `maicli search "keyword" --type doc --plain`\n- [ ] ALL relevant docs read: `maicli doc "Doc Name" --plain`\n- [ ] Similar done tasks reviewed for patterns\n- [ ] Task assigned to self: `-a $(maicli config get defaultAssignee --plain || echo "@me")`\n- [ ] Status set to in-progress: `-s in-progress`\n- [ ] Timer started: `maicli time start <id>`\n\n### During Work\n\n- [ ] Implementation plan created and approved\n- [ ] Doc links included in plan: `@doc/<path>`\n- [ ] Criteria checked as completed: `--check-ac <index>`\n- [ ] Progress notes appended: `--append-notes "\u2713 ..."`\n\n### After Work\n\n- [ ] All acceptance criteria checked (only after work is done)\n- [ ] Implementation notes added: `--notes "..."`\n- [ ] Timer stopped: `maicli time stop`\n- [ ] Tests passing\n- [ ] Documentation updated\n- [ ] Status set to done: `-s done`\n- [ ] Knowledge extracted to docs (if applicable): patterns, solutions, conventions\n\n---\n\n## Quick Reference Card\n\n```bash\n# === AGENT INITIALIZATION (Once per session) ===\nmaicli doc list --plain\nmaicli doc "README" --plain\nmaicli doc "ARCHITECTURE" --plain\nmaicli doc "CONVENTIONS" --plain\n\n# === FULL WORKFLOW ===\nmaicli task create "Title" -d "Description" --ac "Criterion"\nmaicli task edit <id> -s in-progress -a $(maicli config get defaultAssignee --plain || echo "@me")\nmaicli time start <id> # \u23F1\uFE0F REQUIRED: Start timer\nmaicli search "keyword" --type doc --plain\nmaicli doc "Doc Name" --plain\nmaicli search "keyword" --type task --status done --plain # Learn from history\nmaicli task edit <id> --plan $\'1. Step (see @doc/file)\\n2. Step\'\n# ... wait for approval, then implement ...\n# Only check AC AFTER completing the work:\nmaicli task edit <id> --check-ac 1\nmaicli task edit <id> --append-notes "\u2713 Completed: feature X"\nmaicli task edit <id> --check-ac 2\nmaicli task edit <id> --append-notes "\u2713 Completed: feature Y"\nmaicli time stop # \u23F1\uFE0F REQUIRED: Stop timer\nmaicli task edit <id> -s done\n# Optional: Extract knowledge to docs if generalizable patterns found\n\n# === VIEW & SEARCH ===\nmaicli task <id> --plain # Shorthand for view\nmaicli task list --plain\nmaicli task list --status in-progress --assignee $(maicli config get defaultAssignee --plain || echo "@me") --plain\nmaicli search "query" --plain\nmaicli search "bug" --type task --status in-progress --plain\n\n# === TIME TRACKING ===\nmaicli time start <id>\nmaicli time stop\nmaicli time status\nmaicli time report --from "2025-12-01" --to "2025-12-31"\n\n# === DOCUMENTATION ===\nmaicli doc list --plain\nmaicli doc "path/doc-name" --plain # Shorthand for view\nmaicli doc create "Title" -d "Description" -t "tags" -f "folder"\nmaicli doc edit "doc-name" -c "New content"\nmaicli doc edit "doc-name" -a "Appended content"\n```\n\n---\n\n<!-- MAICLI GUIDELINES END -->\n';
47013
47013
 
47014
47014
  // src/templates/maicli-guidelines-mcp.md
47015
- var maicli_guidelines_mcp_default = '<!-- MAICLI GUIDELINES START -->\n# MAICLI MCP Guidelines\n\n## Core Principles\n\n### 1. MCP Tool Operations\n**Use MCP tools for ALL MAICLI operations. NEVER edit .md files directly.**\n\nThis ensures data integrity, maintains proper change history, and prevents file corruption.\n\n### 2. Documentation-First (For AI Agents)\n**ALWAYS read project documentation BEFORE planning or coding.**\n\nAI agents must understand project context, conventions, and existing patterns before making any changes. This prevents rework and ensures consistency.\n\n---\n\n## AI Agent Guidelines\n\n> **CRITICAL**: Before performing ANY task, AI agents MUST read documentation to understand project context.\n\n### First-Time Initialization\n\nWhen starting a new session or working on an unfamiliar project:\n\n```\n# 1. List all available documentation\nmcp__maicli__list_docs({})\n\n# 2. Read essential project docs (prioritize these)\nmcp__maicli__get_doc({ path: "README" })\nmcp__maicli__get_doc({ path: "ARCHITECTURE" })\nmcp__maicli__get_doc({ path: "CONVENTIONS" })\nmcp__maicli__get_doc({ path: "API" })\n\n# 3. Review current task backlog\nmcp__maicli__list_tasks({})\nmcp__maicli__list_tasks({ status: "in-progress" })\n```\n\n### Before Taking Any Task\n\n```\n# 1. View the task details\nmcp__maicli__get_task({ taskId: "<id>" })\n\n# 2. Follow ALL refs in the task (see Reference System section)\n# @.maicli/tasks/task-44 - ... \u2192 mcp__maicli__get_task({ taskId: "44" })\n# @.maicli/docs/patterns/module.md \u2192 mcp__maicli__get_doc({ path: "patterns/module" })\n\n# 3. Search for additional related documentation\nmcp__maicli__search_docs({ query: "<keywords from task>" })\n\n# 4. Read ALL related docs before planning\nmcp__maicli__get_doc({ path: "<related-doc>" })\n\n# 5. Check for similar completed tasks (learn from history)\nmcp__maicli__search_tasks({ query: "<keywords>", status: "done" })\n```\n\n### Why Documentation First?\n\n| Without Reading Docs | With Reading Docs |\n|---------------------|-------------------|\n| Reinvent existing patterns | Reuse established patterns |\n| Break conventions | Follow project standards |\n| Duplicate code | Use existing utilities |\n| Wrong architecture decisions | Align with system design |\n| Inconsistent naming | Match naming conventions |\n\n### Context Checklist for Agents\n\nBefore writing ANY code, ensure you can answer:\n\n- [ ] Have I followed ALL refs (`@.maicli/...`) in the task?\n- [ ] Have I followed nested refs recursively?\n- [ ] What is the project\'s overall architecture?\n- [ ] What coding conventions does this project follow?\n- [ ] Are there existing patterns/utilities I should reuse?\n- [ ] What are the testing requirements?\n- [ ] How should I structure my implementation?\n\n> **Remember**: A few minutes reading docs saves hours of rework. NEVER skip this step.\n\n---\n\n## Reference System (Refs)\n\nTasks and docs can contain **references** to other tasks/docs. AI agents MUST understand and follow these refs to gather complete context.\n\n### Reference Formats\n\n| Type | When Writing (Input) | When Reading (Output) | MCP Tool |\n|------|---------------------|----------------------|----------|\n| **Task ref** | `@task-<id>` | `@.maicli/tasks/task-<id> - <title>.md` | `mcp__maicli__get_task({ taskId: "<id>" })` |\n| **Doc ref** | `@doc/<path>` | `@.maicli/docs/<path>.md` | `mcp__maicli__get_doc({ path: "<path>" })` |\n\n> **CRITICAL for AI Agents**:\n> - When **WRITING** refs (in descriptions, plans, notes): Use `@task-<id>` and `@doc/<path>`\n> - When **READING** output: You\'ll see `@.maicli/tasks/...` and `@.maicli/docs/...`\n> - **NEVER write** the output format (`@.maicli/...`) - always use input format\n\n### How to Follow Refs\n\nWhen you read a task and see refs in system output format, follow them:\n\n```\n# Example: Task 42 output contains:\n# @.maicli/tasks/task-44 - CLI Task Create Command.md\n# @.maicli/docs/patterns/module.md\n\n# Follow task ref (extract ID from task-<id>)\nmcp__maicli__get_task({ taskId: "44" })\n\n# Follow doc ref (extract path, remove .md)\nmcp__maicli__get_doc({ path: "patterns/module" })\n```\n\n### Recursive Following\n\nRefs can be nested. Follow until complete context is gathered:\n\n```\nTask 42\n \u2192 @.maicli/docs/README.md\n \u2192 @.maicli/docs/patterns/module.md (found in README)\n \u2192 (read for full pattern details)\n```\n\n> **CRITICAL**: Never assume you understand a task fully without following its refs. Refs contain essential context that may change your implementation approach.\n\n---\n\n## Quick Start\n\n```\n# Initialize project (use CLI for this)\nmaicli init [name]\n\n# Create task with acceptance criteria\nmcp__maicli__create_task({\n title: "Title",\n description: "Description",\n priority: "high",\n labels: ["label1", "label2"]\n})\n\n# View task\nmcp__maicli__get_task({ taskId: "<id>" })\n\n# List tasks\nmcp__maicli__list_tasks({})\n\n# Search (tasks + docs)\nmcp__maicli__search_tasks({ query: "query" })\nmcp__maicli__search_docs({ query: "query" })\n```\n\n---\n\n## End-to-End Example\n\nHere\'s a complete workflow for an AI agent implementing a feature:\n\n```\n# === AGENT SESSION START (Do this once per session) ===\n\n# 0a. List all available documentation\nmcp__maicli__list_docs({})\n\n# 0b. Read essential project docs\nmcp__maicli__get_doc({ path: "README" })\nmcp__maicli__get_doc({ path: "ARCHITECTURE" })\nmcp__maicli__get_doc({ path: "CONVENTIONS" })\n\n# Now the agent understands project context and conventions\n\n# === TASK WORKFLOW ===\n\n# 1. Create the task\nmcp__maicli__create_task({\n title: "Add password reset flow",\n description: "Users need ability to reset forgotten passwords via email",\n priority: "high",\n labels: ["auth", "feature"]\n})\n\n# Output: Created task 42\n\n# 2. Take the task and start timer\nmcp__maicli__update_task({\n taskId: "42",\n status: "in-progress",\n assignee: "@howznguyen"\n})\nmcp__maicli__start_time({ taskId: "42" })\n\n# 3. Search for related documentation\nmcp__maicli__search_docs({ query: "password security" })\n\n# 4. Read the documentation\nmcp__maicli__get_doc({ path: "security-patterns" })\n\n# 5. Create implementation plan (SHARE WITH USER, WAIT FOR APPROVAL)\nmcp__maicli__update_task({\n taskId: "42",\n plan: "1. Review security patterns (see @doc/security-patterns)\\n2. Design token generation with 1-hour expiry\\n3. Implement /forgot-password endpoint\\n4. Add unit tests"\n})\n\n# 6. After approval, implement and update task progressively\nmcp__maicli__update_task({\n taskId: "42",\n appendNotes: "\u2713 Implemented /forgot-password endpoint"\n})\n\n# 7. Add final implementation notes\nmcp__maicli__update_task({\n taskId: "42",\n notes: "## Summary\\nImplemented complete password reset flow.\\n\\n## Changes\\n- Added POST /forgot-password endpoint\\n- Added POST /reset-password endpoint"\n})\n\n# 8. Stop timer and complete\nmcp__maicli__stop_time({ taskId: "42" })\nmcp__maicli__update_task({\n taskId: "42",\n status: "done"\n})\n```\n\n---\n\n## Task Workflow\n\n### Step 1: Take Task\n\n```\n# Update task status and assign to self\nmcp__maicli__update_task({\n taskId: "<id>",\n status: "in-progress",\n assignee: "@<your-username>"\n})\n```\n\n> **Note**: Use your username as configured in the project. Check project config for `defaultAssignee`.\n\n### Step 2: Start Time Tracking (REQUIRED)\n\n```\nmcp__maicli__start_time({ taskId: "<id>" })\n```\n\n> **CRITICAL**: Time tracking is MANDATORY. Always start timer when taking a task and stop when done. This data is essential for:\n> - Accurate project estimation\n> - Identifying bottlenecks\n> - Resource planning\n> - Sprint retrospectives\n\n### Step 3: Read Related Documentation\n\n> **FOR AI AGENTS**: This step is MANDATORY, not optional. You must understand the codebase before planning.\n\n```\n# Search for related docs\nmcp__maicli__search_docs({ query: "authentication" })\n\n# View relevant documents\nmcp__maicli__get_doc({ path: "API Guidelines" })\nmcp__maicli__get_doc({ path: "Security Patterns" })\n\n# Also check for similar completed tasks\nmcp__maicli__search_tasks({ query: "auth", status: "done" })\n```\n\n> **CRITICAL**: ALWAYS read related documentation BEFORE planning!\n\n### Step 4: Create Implementation Plan\n\n```\nmcp__maicli__update_task({\n taskId: "<id>",\n plan: "1. Research patterns (see @doc/security-patterns)\\n2. Design middleware\\n3. Implement\\n4. Add tests\\n5. Update docs"\n})\n```\n\n> **CRITICAL**:\n> - Share plan with user and **WAIT for approval** before coding\n> - Include doc references using `@doc/<path>` format\n\n### Step 5: Implement\n\n```\n# Work through implementation plan step by step\n# IMPORTANT: Only update task AFTER completing the work, not before\n\n# After completing work, append notes:\nmcp__maicli__update_task({\n taskId: "<id>",\n appendNotes: "\u2713 Completed: <brief description>"\n})\n```\n\n> **CRITICAL**: Never claim work is done before it\'s actually completed.\n\n### Step 6: Handle Dynamic Requests (During Implementation)\n\nIf the user adds new requirements during implementation:\n\n```\n# Append note about scope change\nmcp__maicli__update_task({\n taskId: "<id>",\n appendNotes: "\u26A0\uFE0F Scope updated: Added requirement for X per user request"\n})\n\n# Continue with Step 5 (Implement) for new requirements\n```\n\n> **Note**: Always document scope changes. This helps track why a task took longer than expected.\n\n### Step 7: Add Implementation Notes\n\n```\n# Add comprehensive notes (suitable for PR description)\nmcp__maicli__update_task({\n taskId: "<id>",\n notes: "## Summary\\n\\nImplemented JWT auth.\\n\\n## Changes\\n- Added middleware\\n- Added tests"\n})\n\n# OR append progressively (recommended)\nmcp__maicli__update_task({\n taskId: "<id>",\n appendNotes: "\u2713 Implemented middleware"\n})\n```\n\n### Step 8: Stop Time Tracking (REQUIRED)\n\n```\nmcp__maicli__stop_time({ taskId: "<id>" })\n```\n\n> **CRITICAL**: Never forget to stop the timer. If you forget, use manual entry:\n> `mcp__maicli__add_time({ taskId: "<id>", duration: "2h", note: "Forgot to stop timer" })`\n\n### Step 9: Complete Task\n\n```\nmcp__maicli__update_task({\n taskId: "<id>",\n status: "done"\n})\n```\n\n### Step 10: Handle Post-Completion Changes (If Applicable)\n\nIf the user requests changes or updates AFTER task is marked done:\n\n```\n# 1. Reopen task - set back to in-progress\nmcp__maicli__update_task({\n taskId: "<id>",\n status: "in-progress"\n})\n\n# 2. Restart time tracking (REQUIRED)\nmcp__maicli__start_time({ taskId: "<id>" })\n\n# 3. Document the reopen reason\nmcp__maicli__update_task({\n taskId: "<id>",\n appendNotes: "\u{1F504} Reopened: User requested changes - <reason>"\n})\n\n# 4. Follow Step 5-9 again (Implement \u2192 Notes \u2192 Stop Timer \u2192 Done)\n```\n\n> **CRITICAL**: Treat post-completion changes as a mini-workflow. Always:\n> - Reopen task (in-progress)\n> - Start timer again\n> - Document why it was reopened\n> - Follow the same completion process\n\n### Step 11: Knowledge Extraction (Post-Completion)\n\nAfter completing a task, extract reusable knowledge to docs:\n\n```\n# Search if similar pattern already documented\nmcp__maicli__search_docs({ query: "<pattern/concept>" })\n\n# If new knowledge, create a doc for future reference\nmcp__maicli__create_doc({\n title: "Pattern: <Name>",\n description: "Reusable pattern discovered during task implementation",\n tags: ["pattern", "<domain>"],\n folder: "patterns"\n})\n\n# Or append to existing doc\nmcp__maicli__update_doc({\n path: "<existing-doc>",\n appendContent: "## New Section\\n\\nLearned from task <id>: ..."\n})\n```\n\n**When to extract knowledge:**\n- New patterns/conventions discovered\n- Common error solutions\n- Reusable code snippets or approaches\n- Integration patterns with external services\n- Performance optimization techniques\n\n> **CRITICAL**: Only extract **generalizable** knowledge. Task-specific details belong in implementation notes, not docs.\n\n---\n\n## Essential MCP Tools\n\n### Task Management\n\n```\n# Create task\nmcp__maicli__create_task({\n title: "Title",\n description: "Description",\n priority: "high", # low, medium, high\n labels: ["label1"],\n status: "todo", # todo, in-progress, in-review, done, blocked\n assignee: "@username"\n})\n\n# Get task\nmcp__maicli__get_task({ taskId: "<id>" })\n\n# Update task\nmcp__maicli__update_task({\n taskId: "<id>",\n title: "New title",\n description: "New description",\n status: "in-progress",\n priority: "high",\n assignee: "@username",\n labels: ["new", "labels"],\n plan: "Implementation plan...",\n notes: "Implementation notes...",\n appendNotes: "Append to existing notes..."\n})\n\n# List tasks\nmcp__maicli__list_tasks({})\nmcp__maicli__list_tasks({ status: "in-progress" })\nmcp__maicli__list_tasks({ assignee: "@username" })\nmcp__maicli__list_tasks({ priority: "high" })\nmcp__maicli__list_tasks({ label: "feature" })\n\n# Search tasks\nmcp__maicli__search_tasks({ query: "auth" })\n```\n\n### Time Tracking\n\n```\n# Start timer\nmcp__maicli__start_time({ taskId: "<id>" })\n\n# Stop timer\nmcp__maicli__stop_time({ taskId: "<id>" })\n\n# Manual entry\nmcp__maicli__add_time({\n taskId: "<id>",\n duration: "2h", # e.g., "2h", "30m", "1h30m"\n note: "Optional note",\n date: "2025-12-25" # Optional, defaults to now\n})\n\n# Reports\nmcp__maicli__get_time_report({})\nmcp__maicli__get_time_report({\n from: "2025-12-01",\n to: "2025-12-31",\n groupBy: "task" # task, label, status\n})\n```\n\n### Documentation\n\n```\n# List docs\nmcp__maicli__list_docs({})\nmcp__maicli__list_docs({ tag: "architecture" })\n\n# Get doc\nmcp__maicli__get_doc({ path: "README" })\nmcp__maicli__get_doc({ path: "patterns/module" })\n\n# Create doc\nmcp__maicli__create_doc({\n title: "Title",\n description: "Description",\n tags: ["tag1", "tag2"],\n folder: "folder/path", # Optional\n content: "Initial content..."\n})\n\n# Update doc\nmcp__maicli__update_doc({\n path: "doc-name",\n title: "New Title",\n description: "New description",\n tags: ["new", "tags"],\n content: "Replace content...",\n appendContent: "Append to content..."\n})\n\n# Search docs\nmcp__maicli__search_docs({ query: "patterns" })\nmcp__maicli__search_docs({ query: "auth", tag: "security" })\n```\n\n### Board\n\n```\n# Get kanban board view\nmcp__maicli__get_board({})\n```\n\n---\n\n## Task Structure\n\n### Title\n\nClear summary (WHAT needs to be done).\n\n| Bad | Good |\n|-----|------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout on slow networks |\n| Update docs | Document rate limiting in API.md |\n\n### Description\n\nExplains WHY and WHAT (not HOW). **Link related docs using `@doc/<path>`**\n\n```\nWe need JWT authentication because sessions don\'t scale for our microservices architecture.\n\nRelated docs: @doc/security-patterns, @doc/api-guidelines\n```\n\n### Acceptance Criteria\n\n**Outcome-oriented**, testable criteria. NOT implementation steps.\n\n| Bad (Implementation details) | Good (Outcomes) |\n|------------------------------|-----------------|\n| Add function handleLogin() in auth.ts | User can login and receive JWT token |\n| Use bcrypt for hashing | Passwords are securely hashed |\n| Add try-catch blocks | Errors return appropriate HTTP status codes |\n\n---\n\n## Definition of Done\n\nA task is **Done** ONLY when **ALL** criteria are met:\n\n### Via MCP Tools (Required)\n\n- [ ] All work completed and verified\n- [ ] Implementation notes added via `update_task`\n- [ ] \u23F1\uFE0F Timer stopped: `mcp__maicli__stop_time` (MANDATORY - do not skip!)\n- [ ] Status set to done via `update_task`\n- [ ] Knowledge extracted to docs (if applicable)\n\n### Via Code (Required)\n\n- [ ] All tests pass\n- [ ] Documentation updated\n- [ ] Code reviewed (linting, formatting)\n- [ ] No regressions introduced\n\n---\n\n## Status & Priority Reference\n\n### Status Values\n\n| Status | Description | When to Use |\n|--------|-------------|-------------|\n| `todo` | Not started | Default for new tasks |\n| `in-progress` | Currently working | After taking task |\n| `in-review` | In code review | PR submitted |\n| `blocked` | Waiting on dependency | External blocker |\n| `done` | Completed | All criteria met |\n\n### Priority Values\n\n| Priority | Description |\n|----------|-------------|\n| `low` | Can wait, nice-to-have |\n| `medium` | Normal priority (default) |\n| `high` | Urgent, time-sensitive |\n\n---\n\n## Common Mistakes\n\n| Wrong | Right |\n|-------|-------|\n| Edit .md files directly | Use MCP tools |\n| Skip time tracking | ALWAYS use `start_time` and `stop_time` |\n| Start coding without reading docs | Read ALL related docs FIRST |\n| Plan without checking docs | Read docs before planning |\n| Code before plan approval | Share plan, WAIT for approval |\n| Mark done without all criteria | Verify ALL criteria first |\n| Ignore refs in task description | Follow ALL refs before planning |\n| Follow only first-level refs | Recursively follow nested refs |\n\n---\n\n## Best Practices Checklist\n\n### For AI Agents: Session Start\n\n- [ ] List all docs: `mcp__maicli__list_docs({})`\n- [ ] Read README/ARCHITECTURE docs\n- [ ] Understand coding conventions\n- [ ] Review current task backlog\n\n### Before Starting Work\n\n- [ ] Task details retrieved: `mcp__maicli__get_task`\n- [ ] ALL refs in task followed\n- [ ] Nested refs recursively followed\n- [ ] Related docs searched and read\n- [ ] Similar done tasks reviewed for patterns\n- [ ] Task assigned to self via `update_task`\n- [ ] Status set to in-progress\n- [ ] Timer started: `mcp__maicli__start_time`\n\n### During Work\n\n- [ ] Implementation plan created and approved\n- [ ] Doc links included in plan: `@doc/<path>`\n- [ ] Progress notes appended: `appendNotes`\n\n### After Work\n\n- [ ] All work verified complete\n- [ ] Implementation notes added\n- [ ] Timer stopped: `mcp__maicli__stop_time`\n- [ ] Tests passing\n- [ ] Documentation updated\n- [ ] Status set to done\n- [ ] Knowledge extracted to docs (if applicable)\n\n---\n\n## Quick Reference\n\n```\n# === AGENT INITIALIZATION (Once per session) ===\nmcp__maicli__list_docs({})\nmcp__maicli__get_doc({ path: "README" })\nmcp__maicli__get_doc({ path: "ARCHITECTURE" })\nmcp__maicli__get_doc({ path: "CONVENTIONS" })\n\n# === FULL WORKFLOW ===\nmcp__maicli__create_task({ title: "Title", description: "Description" })\nmcp__maicli__update_task({ taskId: "<id>", status: "in-progress", assignee: "@me" })\nmcp__maicli__start_time({ taskId: "<id>" }) # \u23F1\uFE0F REQUIRED\nmcp__maicli__search_docs({ query: "keyword" })\nmcp__maicli__get_doc({ path: "Doc Name" })\nmcp__maicli__search_tasks({ query: "keyword", status: "done" }) # Learn from history\nmcp__maicli__update_task({ taskId: "<id>", plan: "1. Step\\n2. Step" })\n# ... wait for approval, then implement ...\nmcp__maicli__update_task({ taskId: "<id>", appendNotes: "\u2713 Completed: feature X" })\nmcp__maicli__stop_time({ taskId: "<id>" }) # \u23F1\uFE0F REQUIRED\nmcp__maicli__update_task({ taskId: "<id>", status: "done" })\n# Optional: Extract knowledge to docs if generalizable patterns found\n\n# === VIEW & SEARCH ===\nmcp__maicli__get_task({ taskId: "<id>" })\nmcp__maicli__list_tasks({})\nmcp__maicli__list_tasks({ status: "in-progress", assignee: "@me" })\nmcp__maicli__search_tasks({ query: "bug" })\nmcp__maicli__search_docs({ query: "pattern" })\n\n# === TIME TRACKING ===\nmcp__maicli__start_time({ taskId: "<id>" })\nmcp__maicli__stop_time({ taskId: "<id>" })\nmcp__maicli__add_time({ taskId: "<id>", duration: "2h" })\nmcp__maicli__get_time_report({})\n\n# === DOCUMENTATION ===\nmcp__maicli__list_docs({})\nmcp__maicli__get_doc({ path: "path/doc-name" })\nmcp__maicli__create_doc({ title: "Title", description: "Desc", tags: ["tag"] })\nmcp__maicli__update_doc({ path: "doc-name", appendContent: "New content" })\n```\n\n---\n\n**Maintained By**: MAICLI Team\n\n<!-- MAICLI GUIDELINES END -->\n';
47015
+ var maicli_guidelines_mcp_default = '<!-- MAICLI GUIDELINES START -->\n# MAICLI MCP Guidelines\n\n## Core Principles\n\n### 1. MCP Tool Operations\n**Use MCP tools for ALL MAICLI operations. NEVER edit .md files directly.**\n\nThis ensures data integrity, maintains proper change history, and prevents file corruption.\n\n### 2. Documentation-First (For AI Agents)\n**ALWAYS read project documentation BEFORE planning or coding.**\n\nAI agents must understand project context, conventions, and existing patterns before making any changes. This prevents rework and ensures consistency.\n\n---\n\n## AI Agent Guidelines\n\n> **CRITICAL**: Before performing ANY task, AI agents MUST read documentation to understand project context.\n\n### First-Time Initialization\n\nWhen starting a new session or working on an unfamiliar project:\n\n```\n# 1. List all available documentation\nmcp__maicli__list_docs({})\n\n# 2. Read essential project docs (prioritize these)\nmcp__maicli__get_doc({ path: "README" })\nmcp__maicli__get_doc({ path: "ARCHITECTURE" })\nmcp__maicli__get_doc({ path: "CONVENTIONS" })\nmcp__maicli__get_doc({ path: "API" })\n\n# 3. Review current task backlog\nmcp__maicli__list_tasks({})\nmcp__maicli__list_tasks({ status: "in-progress" })\n```\n\n### Before Taking Any Task\n\n```\n# 1. View the task details\nmcp__maicli__get_task({ taskId: "<id>" })\n\n# 2. Follow ALL refs in the task (see Reference System section)\n# @.maicli/tasks/task-44 - ... \u2192 mcp__maicli__get_task({ taskId: "44" })\n# @.maicli/docs/patterns/module.md \u2192 mcp__maicli__get_doc({ path: "patterns/module" })\n\n# 3. Search for additional related documentation\nmcp__maicli__search_docs({ query: "<keywords from task>" })\n\n# 4. Read ALL related docs before planning\nmcp__maicli__get_doc({ path: "<related-doc>" })\n\n# 5. Check for similar completed tasks (learn from history)\nmcp__maicli__search_tasks({ query: "<keywords>", status: "done" })\n```\n\n### Why Documentation First?\n\n| Without Reading Docs | With Reading Docs |\n|---------------------|-------------------|\n| Reinvent existing patterns | Reuse established patterns |\n| Break conventions | Follow project standards |\n| Duplicate code | Use existing utilities |\n| Wrong architecture decisions | Align with system design |\n| Inconsistent naming | Match naming conventions |\n\n### Context Checklist for Agents\n\nBefore writing ANY code, ensure you can answer:\n\n- [ ] Have I followed ALL refs (`@.maicli/...`) in the task?\n- [ ] Have I followed nested refs recursively?\n- [ ] What is the project\'s overall architecture?\n- [ ] What coding conventions does this project follow?\n- [ ] Are there existing patterns/utilities I should reuse?\n- [ ] What are the testing requirements?\n- [ ] How should I structure my implementation?\n\n> **Remember**: A few minutes reading docs saves hours of rework. NEVER skip this step.\n\n---\n\n## Reference System (Refs)\n\nTasks and docs can contain **references** to other tasks/docs. AI agents MUST understand and follow these refs to gather complete context.\n\n### Reference Formats\n\n| Type | When Writing (Input) | When Reading (Output) | MCP Tool |\n|------|---------------------|----------------------|----------|\n| **Task ref** | `@task-<id>` | `@.maicli/tasks/task-<id> - <title>.md` | `mcp__maicli__get_task({ taskId: "<id>" })` |\n| **Doc ref** | `@doc/<path>` | `@.maicli/docs/<path>.md` | `mcp__maicli__get_doc({ path: "<path>" })` |\n\n> **CRITICAL for AI Agents**:\n> - When **WRITING** refs (in descriptions, plans, notes): Use `@task-<id>` and `@doc/<path>`\n> - When **READING** output: You\'ll see `@.maicli/tasks/...` and `@.maicli/docs/...`\n> - **NEVER write** the output format (`@.maicli/...`) - always use input format\n\n### How to Follow Refs\n\nWhen you read a task and see refs in system output format, follow them:\n\n```\n# Example: Task 42 output contains:\n# @.maicli/tasks/task-44 - CLI Task Create Command.md\n# @.maicli/docs/patterns/module.md\n\n# Follow task ref (extract ID from task-<id>)\nmcp__maicli__get_task({ taskId: "44" })\n\n# Follow doc ref (extract path, remove .md)\nmcp__maicli__get_doc({ path: "patterns/module" })\n```\n\n### Recursive Following\n\nRefs can be nested. Follow until complete context is gathered:\n\n```\nTask 42\n \u2192 @.maicli/docs/README.md\n \u2192 @.maicli/docs/patterns/module.md (found in README)\n \u2192 (read for full pattern details)\n```\n\n> **CRITICAL**: Never assume you understand a task fully without following its refs. Refs contain essential context that may change your implementation approach.\n\n---\n\n## Quick Start\n\n```\n# Initialize project (use CLI for this)\nmaicli init [name]\n\n# Create task with acceptance criteria\nmcp__maicli__create_task({\n title: "Title",\n description: "Description",\n priority: "high",\n labels: ["label1", "label2"]\n})\n\n# View task\nmcp__maicli__get_task({ taskId: "<id>" })\n\n# List tasks\nmcp__maicli__list_tasks({})\n\n# Search (tasks + docs)\nmcp__maicli__search_tasks({ query: "query" })\nmcp__maicli__search_docs({ query: "query" })\n```\n\n---\n\n## End-to-End Example\n\nHere\'s a complete workflow for an AI agent implementing a feature:\n\n```\n# === AGENT SESSION START (Do this once per session) ===\n\n# 0a. List all available documentation\nmcp__maicli__list_docs({})\n\n# 0b. Read essential project docs\nmcp__maicli__get_doc({ path: "README" })\nmcp__maicli__get_doc({ path: "ARCHITECTURE" })\nmcp__maicli__get_doc({ path: "CONVENTIONS" })\n\n# Now the agent understands project context and conventions\n\n# === TASK WORKFLOW ===\n\n# 1. Create the task\nmcp__maicli__create_task({\n title: "Add password reset flow",\n description: "Users need ability to reset forgotten passwords via email",\n priority: "high",\n labels: ["auth", "feature"]\n})\n\n# Output: Created task 42\n\n# 2. Take the task and start timer\nmcp__maicli__update_task({\n taskId: "42",\n status: "in-progress",\n assignee: "@howznguyen"\n})\nmcp__maicli__start_time({ taskId: "42" })\n\n# 3. Search for related documentation\nmcp__maicli__search_docs({ query: "password security" })\n\n# 4. Read the documentation\nmcp__maicli__get_doc({ path: "security-patterns" })\n\n# 5. Create implementation plan (SHARE WITH USER, WAIT FOR APPROVAL)\nmcp__maicli__update_task({\n taskId: "42",\n plan: "1. Review security patterns (see @doc/security-patterns)\\n2. Design token generation with 1-hour expiry\\n3. Implement /forgot-password endpoint\\n4. Add unit tests"\n})\n\n# 6. After approval, implement and update task progressively\nmcp__maicli__update_task({\n taskId: "42",\n appendNotes: "\u2713 Implemented /forgot-password endpoint"\n})\n\n# 7. Add final implementation notes\nmcp__maicli__update_task({\n taskId: "42",\n notes: "## Summary\\nImplemented complete password reset flow.\\n\\n## Changes\\n- Added POST /forgot-password endpoint\\n- Added POST /reset-password endpoint"\n})\n\n# 8. Stop timer and complete\nmcp__maicli__stop_time({ taskId: "42" })\nmcp__maicli__update_task({\n taskId: "42",\n status: "done"\n})\n```\n\n---\n\n## Task Workflow\n\n### Step 1: Take Task\n\n```\n# Update task status and assign to self\nmcp__maicli__update_task({\n taskId: "<id>",\n status: "in-progress",\n assignee: "@<your-username>"\n})\n```\n\n> **Note**: Use your username as configured in the project. Check project config for `defaultAssignee`.\n\n### Step 2: Start Time Tracking (REQUIRED)\n\n```\nmcp__maicli__start_time({ taskId: "<id>" })\n```\n\n> **CRITICAL**: Time tracking is MANDATORY. Always start timer when taking a task and stop when done. This data is essential for:\n> - Accurate project estimation\n> - Identifying bottlenecks\n> - Resource planning\n> - Sprint retrospectives\n\n### Step 3: Read Related Documentation\n\n> **FOR AI AGENTS**: This step is MANDATORY, not optional. You must understand the codebase before planning.\n\n```\n# Search for related docs\nmcp__maicli__search_docs({ query: "authentication" })\n\n# View relevant documents\nmcp__maicli__get_doc({ path: "API Guidelines" })\nmcp__maicli__get_doc({ path: "Security Patterns" })\n\n# Also check for similar completed tasks\nmcp__maicli__search_tasks({ query: "auth", status: "done" })\n```\n\n> **CRITICAL**: ALWAYS read related documentation BEFORE planning!\n\n### Step 4: Create Implementation Plan\n\n```\nmcp__maicli__update_task({\n taskId: "<id>",\n plan: "1. Research patterns (see @doc/security-patterns)\\n2. Design middleware\\n3. Implement\\n4. Add tests\\n5. Update docs"\n})\n```\n\n> **CRITICAL**:\n> - Share plan with user and **WAIT for approval** before coding\n> - Include doc references using `@doc/<path>` format\n\n### Step 5: Implement\n\n```\n# Work through implementation plan step by step\n# IMPORTANT: Only update task AFTER completing the work, not before\n\n# After completing work, append notes:\nmcp__maicli__update_task({\n taskId: "<id>",\n appendNotes: "\u2713 Completed: <brief description>"\n})\n```\n\n> **CRITICAL**: Never claim work is done before it\'s actually completed.\n\n### Step 6: Handle Dynamic Requests (During Implementation)\n\nIf the user adds new requirements during implementation:\n\n```\n# Append note about scope change\nmcp__maicli__update_task({\n taskId: "<id>",\n appendNotes: "\u26A0\uFE0F Scope updated: Added requirement for X per user request"\n})\n\n# Continue with Step 5 (Implement) for new requirements\n```\n\n> **Note**: Always document scope changes. This helps track why a task took longer than expected.\n\n### Step 7: Add Implementation Notes\n\n```\n# Add comprehensive notes (suitable for PR description)\nmcp__maicli__update_task({\n taskId: "<id>",\n notes: "## Summary\\n\\nImplemented JWT auth.\\n\\n## Changes\\n- Added middleware\\n- Added tests"\n})\n\n# OR append progressively (recommended)\nmcp__maicli__update_task({\n taskId: "<id>",\n appendNotes: "\u2713 Implemented middleware"\n})\n```\n\n### Step 8: Stop Time Tracking (REQUIRED)\n\n```\nmcp__maicli__stop_time({ taskId: "<id>" })\n```\n\n> **CRITICAL**: Never forget to stop the timer. If you forget, use manual entry:\n> `mcp__maicli__add_time({ taskId: "<id>", duration: "2h", note: "Forgot to stop timer" })`\n\n### Step 9: Complete Task\n\n```\nmcp__maicli__update_task({\n taskId: "<id>",\n status: "done"\n})\n```\n\n### Step 10: Handle Post-Completion Changes (If Applicable)\n\nIf the user requests changes or updates AFTER task is marked done:\n\n```\n# 1. Reopen task - set back to in-progress\nmcp__maicli__update_task({\n taskId: "<id>",\n status: "in-progress"\n})\n\n# 2. Restart time tracking (REQUIRED)\nmcp__maicli__start_time({ taskId: "<id>" })\n\n# 3. Document the reopen reason\nmcp__maicli__update_task({\n taskId: "<id>",\n appendNotes: "\u{1F504} Reopened: User requested changes - <reason>"\n})\n\n# 4. Follow Step 5-9 again (Implement \u2192 Notes \u2192 Stop Timer \u2192 Done)\n```\n\n> **CRITICAL**: Treat post-completion changes as a mini-workflow. Always:\n> - Reopen task (in-progress)\n> - Start timer again\n> - Document why it was reopened\n> - Follow the same completion process\n\n### Step 11: Knowledge Extraction (Post-Completion)\n\nAfter completing a task, extract reusable knowledge to docs:\n\n```\n# Search if similar pattern already documented\nmcp__maicli__search_docs({ query: "<pattern/concept>" })\n\n# If new knowledge, create a doc for future reference\nmcp__maicli__create_doc({\n title: "Pattern: <Name>",\n description: "Reusable pattern discovered during task implementation",\n tags: ["pattern", "<domain>"],\n folder: "patterns"\n})\n\n# Or append to existing doc\nmcp__maicli__update_doc({\n path: "<existing-doc>",\n appendContent: "## New Section\\n\\nLearned from task <id>: ..."\n})\n```\n\n**When to extract knowledge:**\n- New patterns/conventions discovered\n- Common error solutions\n- Reusable code snippets or approaches\n- Integration patterns with external services\n- Performance optimization techniques\n\n> **CRITICAL**: Only extract **generalizable** knowledge. Task-specific details belong in implementation notes, not docs.\n\n---\n\n## Essential MCP Tools\n\n### Task Management\n\n```\n# Create task\nmcp__maicli__create_task({\n title: "Title",\n description: "Description",\n priority: "high", # low, medium, high\n labels: ["label1"],\n status: "todo", # todo, in-progress, in-review, done, blocked\n assignee: "@username"\n})\n\n# Get task\nmcp__maicli__get_task({ taskId: "<id>" })\n\n# Update task\nmcp__maicli__update_task({\n taskId: "<id>",\n title: "New title",\n description: "New description",\n status: "in-progress",\n priority: "high",\n assignee: "@username",\n labels: ["new", "labels"],\n plan: "Implementation plan...",\n notes: "Implementation notes...",\n appendNotes: "Append to existing notes..."\n})\n\n# List tasks\nmcp__maicli__list_tasks({})\nmcp__maicli__list_tasks({ status: "in-progress" })\nmcp__maicli__list_tasks({ assignee: "@username" })\nmcp__maicli__list_tasks({ priority: "high" })\nmcp__maicli__list_tasks({ label: "feature" })\n\n# Search tasks\nmcp__maicli__search_tasks({ query: "auth" })\n```\n\n### Time Tracking\n\n```\n# Start timer\nmcp__maicli__start_time({ taskId: "<id>" })\n\n# Stop timer\nmcp__maicli__stop_time({ taskId: "<id>" })\n\n# Manual entry\nmcp__maicli__add_time({\n taskId: "<id>",\n duration: "2h", # e.g., "2h", "30m", "1h30m"\n note: "Optional note",\n date: "2025-12-25" # Optional, defaults to now\n})\n\n# Reports\nmcp__maicli__get_time_report({})\nmcp__maicli__get_time_report({\n from: "2025-12-01",\n to: "2025-12-31",\n groupBy: "task" # task, label, status\n})\n```\n\n### Documentation\n\n```\n# List docs\nmcp__maicli__list_docs({})\nmcp__maicli__list_docs({ tag: "architecture" })\n\n# Get doc\nmcp__maicli__get_doc({ path: "README" })\nmcp__maicli__get_doc({ path: "patterns/module" })\n\n# Create doc\nmcp__maicli__create_doc({\n title: "Title",\n description: "Description",\n tags: ["tag1", "tag2"],\n folder: "folder/path", # Optional\n content: "Initial content..."\n})\n\n# Update doc\nmcp__maicli__update_doc({\n path: "doc-name",\n title: "New Title",\n description: "New description",\n tags: ["new", "tags"],\n content: "Replace content...",\n appendContent: "Append to content..."\n})\n\n# Search docs\nmcp__maicli__search_docs({ query: "patterns" })\nmcp__maicli__search_docs({ query: "auth", tag: "security" })\n```\n\n### Board\n\n```\n# Get kanban board view\nmcp__maicli__get_board({})\n```\n\n---\n\n## Task Structure\n\n### Title\n\nClear summary (WHAT needs to be done).\n\n| Bad | Good |\n|-----|------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout on slow networks |\n| Update docs | Document rate limiting in API.md |\n\n### Description\n\nExplains WHY and WHAT (not HOW). **Link related docs using `@doc/<path>`**\n\n```\nWe need JWT authentication because sessions don\'t scale for our microservices architecture.\n\nRelated docs: @doc/security-patterns, @doc/api-guidelines\n```\n\n### Acceptance Criteria\n\n**Outcome-oriented**, testable criteria. NOT implementation steps.\n\n| Bad (Implementation details) | Good (Outcomes) |\n|------------------------------|-----------------|\n| Add function handleLogin() in auth.ts | User can login and receive JWT token |\n| Use bcrypt for hashing | Passwords are securely hashed |\n| Add try-catch blocks | Errors return appropriate HTTP status codes |\n\n---\n\n## Definition of Done\n\nA task is **Done** ONLY when **ALL** criteria are met:\n\n### Via MCP Tools (Required)\n\n- [ ] All work completed and verified\n- [ ] Implementation notes added via `update_task`\n- [ ] \u23F1\uFE0F Timer stopped: `mcp__maicli__stop_time` (MANDATORY - do not skip!)\n- [ ] Status set to done via `update_task`\n- [ ] Knowledge extracted to docs (if applicable)\n\n### Via Code (Required)\n\n- [ ] All tests pass\n- [ ] Documentation updated\n- [ ] Code reviewed (linting, formatting)\n- [ ] No regressions introduced\n\n---\n\n## Status & Priority Reference\n\n### Status Values\n\n| Status | Description | When to Use |\n|--------|-------------|-------------|\n| `todo` | Not started | Default for new tasks |\n| `in-progress` | Currently working | After taking task |\n| `in-review` | In code review | PR submitted |\n| `blocked` | Waiting on dependency | External blocker |\n| `done` | Completed | All criteria met |\n\n### Priority Values\n\n| Priority | Description |\n|----------|-------------|\n| `low` | Can wait, nice-to-have |\n| `medium` | Normal priority (default) |\n| `high` | Urgent, time-sensitive |\n\n---\n\n## Common Mistakes\n\n| Wrong | Right |\n|-------|-------|\n| Edit .md files directly | Use MCP tools |\n| Skip time tracking | ALWAYS use `start_time` and `stop_time` |\n| Start coding without reading docs | Read ALL related docs FIRST |\n| Plan without checking docs | Read docs before planning |\n| Code before plan approval | Share plan, WAIT for approval |\n| Mark done without all criteria | Verify ALL criteria first |\n| Ignore refs in task description | Follow ALL refs before planning |\n| Follow only first-level refs | Recursively follow nested refs |\n\n---\n\n## Best Practices Checklist\n\n### For AI Agents: Session Start\n\n- [ ] List all docs: `mcp__maicli__list_docs({})`\n- [ ] Read README/ARCHITECTURE docs\n- [ ] Understand coding conventions\n- [ ] Review current task backlog\n\n### Before Starting Work\n\n- [ ] Task details retrieved: `mcp__maicli__get_task`\n- [ ] ALL refs in task followed\n- [ ] Nested refs recursively followed\n- [ ] Related docs searched and read\n- [ ] Similar done tasks reviewed for patterns\n- [ ] Task assigned to self via `update_task`\n- [ ] Status set to in-progress\n- [ ] Timer started: `mcp__maicli__start_time`\n\n### During Work\n\n- [ ] Implementation plan created and approved\n- [ ] Doc links included in plan: `@doc/<path>`\n- [ ] Progress notes appended: `appendNotes`\n\n### After Work\n\n- [ ] All work verified complete\n- [ ] Implementation notes added\n- [ ] Timer stopped: `mcp__maicli__stop_time`\n- [ ] Tests passing\n- [ ] Documentation updated\n- [ ] Status set to done\n- [ ] Knowledge extracted to docs (if applicable)\n\n---\n\n## Quick Reference\n\n```\n# === AGENT INITIALIZATION (Once per session) ===\nmcp__maicli__list_docs({})\nmcp__maicli__get_doc({ path: "README" })\nmcp__maicli__get_doc({ path: "ARCHITECTURE" })\nmcp__maicli__get_doc({ path: "CONVENTIONS" })\n\n# === FULL WORKFLOW ===\nmcp__maicli__create_task({ title: "Title", description: "Description" })\nmcp__maicli__update_task({ taskId: "<id>", status: "in-progress", assignee: "@me" })\nmcp__maicli__start_time({ taskId: "<id>" }) # \u23F1\uFE0F REQUIRED\nmcp__maicli__search_docs({ query: "keyword" })\nmcp__maicli__get_doc({ path: "Doc Name" })\nmcp__maicli__search_tasks({ query: "keyword", status: "done" }) # Learn from history\nmcp__maicli__update_task({ taskId: "<id>", plan: "1. Step\\n2. Step" })\n# ... wait for approval, then implement ...\nmcp__maicli__update_task({ taskId: "<id>", appendNotes: "\u2713 Completed: feature X" })\nmcp__maicli__stop_time({ taskId: "<id>" }) # \u23F1\uFE0F REQUIRED\nmcp__maicli__update_task({ taskId: "<id>", status: "done" })\n# Optional: Extract knowledge to docs if generalizable patterns found\n\n# === VIEW & SEARCH ===\nmcp__maicli__get_task({ taskId: "<id>" })\nmcp__maicli__list_tasks({})\nmcp__maicli__list_tasks({ status: "in-progress", assignee: "@me" })\nmcp__maicli__search_tasks({ query: "bug" })\nmcp__maicli__search_docs({ query: "pattern" })\n\n# === TIME TRACKING ===\nmcp__maicli__start_time({ taskId: "<id>" })\nmcp__maicli__stop_time({ taskId: "<id>" })\nmcp__maicli__add_time({ taskId: "<id>", duration: "2h" })\nmcp__maicli__get_time_report({})\n\n# === DOCUMENTATION ===\nmcp__maicli__list_docs({})\nmcp__maicli__get_doc({ path: "path/doc-name" })\nmcp__maicli__create_doc({ title: "Title", description: "Desc", tags: ["tag"] })\nmcp__maicli__update_doc({ path: "doc-name", appendContent: "New content" })\n```\n\n---\n\n<!-- MAICLI GUIDELINES END -->\n';
47016
47016
 
47017
47017
  // src/commands/agents.ts
47018
47018
  import { existsSync } from "node:fs";
@@ -72849,8 +72849,8 @@ function showConfigInfo() {
72849
72849
 
72850
72850
  // package.json
72851
72851
  var package_default = {
72852
- name: "maicli",
72853
- version: "0.3.1",
72852
+ name: "@hunghg255/maicli",
72853
+ version: "0.0.2",
72854
72854
  description: "CLI tool for dev teams to manage tasks and documentation",
72855
72855
  module: "index.ts",
72856
72856
  type: "module",
@@ -72874,7 +72874,7 @@ var package_default = {
72874
72874
  "team-tools",
72875
72875
  "developer-tools"
72876
72876
  ],
72877
- author: "howznguyen <howznguyen@maicli.dev>",
72877
+ author: "hunghg255",
72878
72878
  license: "MIT",
72879
72879
  engines: {
72880
72880
  node: ">=18.0.0"
@@ -72983,9 +72983,6 @@ function showBanner() {
72983
72983
  console.log(source_default.gray(" maicli browser Open web UI"));
72984
72984
  console.log(source_default.gray(" maicli --help Show all commands"));
72985
72985
  console.log();
72986
- console.log(source_default.gray(" Homepage: ") + source_default.cyan("https://maicli.dev"));
72987
- console.log(source_default.gray(" Documents: ") + source_default.cyan("https://cli.maicli.dev/docs"));
72988
- console.log();
72989
72986
  }
72990
72987
  var program2 = new Command();
72991
72988
  program2.name("maicli").description("CLI tool for dev teams to manage tasks, track time, and sync").version(package_default.version);