@hunghg255/maicli 0.0.1

package/CLAUDE.md

@@ -0,0 +1,898 @@
+<!-- MAICLI GUIDELINES START -->
+# MAICLI Guidelines
+
+## Core Principles
+
+### 1. CLI-Only Operations
+**NEVER edit .md files directly. ALL operations MUST use CLI commands.**
+
+This ensures data integrity, maintains proper change history, and prevents file corruption.
+
+### 2. Documentation-First (For AI Agents)
+**ALWAYS read project documentation BEFORE planning or coding.**
+
+AI agents must understand project context, conventions, and existing patterns before making any changes. This prevents rework and ensures consistency.
+
+---
+
+## AI Agent Guidelines
+
+> **CRITICAL**: Before performing ANY task, AI agents MUST read documentation to understand project context.
+
+### First-Time Initialization
+
+When starting a new session or working on an unfamiliar project:
+
+```bash
+# 1. List all available documentation
+maicli doc list --plain
+
+# 2. Read essential project docs (prioritize these)
+maicli doc "README" --plain                # Project overview
+maicli doc "ARCHITECTURE" --plain          # System design
+maicli doc "CONVENTIONS" --plain           # Coding standards
+maicli doc "API" --plain                   # API specifications
+
+# 3. Review current task backlog
+maicli task list --plain
+maicli task list --status in-progress --plain
+```
+
+### Before Taking Any Task
+
+```bash
+# 1. View the task details
+maicli task <id> --plain
+
+# 2. Follow ALL refs in the task (see Reference System section)
+# @.maicli/tasks/task-44 - ... → maicli task 44 --plain
+# @.maicli/docs/patterns/module.md → maicli doc "patterns/module" --plain
+
+# 3. Search for additional related documentation
+maicli search "<keywords from task>" --type doc --plain
+
+# 4. Read ALL related docs before planning
+maicli doc "<related-doc>" --plain
+
+# 5. Check for similar completed tasks (learn from history)
+maicli search "<keywords>" --type task --status done --plain
+```
+
+### Why Documentation First?
+
+| Without Reading Docs | With Reading Docs |
+|---------------------|-------------------|
+| Reinvent existing patterns | Reuse established patterns |
+| Break conventions | Follow project standards |
+| Duplicate code | Use existing utilities |
+| Wrong architecture decisions | Align with system design |
+| Inconsistent naming | Match naming conventions |
+
+### Context Checklist for Agents
+
+Before writing ANY code, ensure you can answer:
+
+- [ ] Have I followed ALL refs (`@.maicli/...`) in the task?
+- [ ] Have I followed nested refs recursively?
+- [ ] What is the project's overall architecture?
+- [ ] What coding conventions does this project follow?
+- [ ] Are there existing patterns/utilities I should reuse?
+- [ ] What are the testing requirements?
+- [ ] How should I structure my implementation?
+
+> **Remember**: A few minutes reading docs saves hours of rework. NEVER skip this step.
+
+---
+
+## Reference System (Refs)
+
+Tasks and docs can contain **references** to other tasks/docs. AI agents MUST understand and follow these refs to gather complete context.
+
+### Reference Formats
+
+| Type | When Writing (Input) | When Reading (Output) | CLI Command |
+|------|---------------------|----------------------|-------------|
+| **Task ref** | `@task-<id>` | `@.maicli/tasks/task-<id> - <title>.md` | `maicli task <id> --plain` |
+| **Doc ref** | `@doc/<path>` | `@.maicli/docs/<path>.md` | `maicli doc <path> --plain` |
+
+> **CRITICAL for AI Agents**:
+> - When **WRITING** refs (in descriptions, plans, notes): Use `@task-<id>` and `@doc/<path>`
+> - When **READING** output from `--plain`: You'll see `@.maicli/tasks/...` and `@.maicli/docs/...`
+> - **NEVER write** the output format (`@.maicli/...`) - always use input format (`@task-<id>`, `@doc/<path>`)
+
+### How to Follow Refs
+
+When you read a task and see refs in system output format, follow them:
+
+```bash
+# Example: Task 42 output contains:
+# @.maicli/tasks/task-44 - CLI Task Create Command.md
+# @.maicli/docs/patterns/module.md
+
+# Follow task ref (extract ID from task-<id>)
+maicli task 44 --plain
+
+# Follow doc ref (extract path, remove .md)
+maicli doc "patterns/module" --plain
+```
+
+### Parsing Rules
+
+1. **Task refs**: `@.maicli/tasks/task-<id> - ...` → extract `<id>` → `maicli task <id> --plain`
+2. **Doc refs**: `@.maicli/docs/<path>.md` → extract `<path>` → `maicli doc "<path>" --plain`
+
+### Recursive Following
+
+Refs can be nested. Follow until complete context is gathered:
+
+```
+Task 42
+  → @.maicli/docs/README.md
+    → @.maicli/docs/patterns/module.md (found in README)
+      → (read for full pattern details)
+```
+
+### When to Follow Refs
+
+| Situation | Action |
+|-----------|--------|
+| Refs in Description | ALWAYS follow - critical context |
+| Refs in Implementation Plan | Follow if implementing related work |
+| Refs in Notes | Optional - for historical context |
+| Dependency mentions | Follow if marked as blocker |
+
+### Example: Complete Ref Resolution
+
+```bash
+# 1. Read the task
+$ maicli task 42 --plain
+
+# Output contains:
+# @.maicli/tasks/task-44 - CLI Task Create Command.md
+# @.maicli/docs/README.md
+
+# 2. Follow task ref
+$ maicli task 44 --plain
+
+# 3. Follow doc ref
+$ maicli doc "README" --plain
+
+# 4. If README contains more refs, follow them too
+# @.maicli/docs/patterns/module.md → maicli doc "patterns/module" --plain
+
+# Now you have complete context
+```
+
+> **CRITICAL**: Never assume you understand a task fully without following its refs. Refs contain essential context that may change your implementation approach.
+
+---
+
+## Quick Start
+
+```bash
+# Initialize project
+maicli init [name]
+
+# Create task with acceptance criteria
+maicli task create "Title" -d "Description" --ac "Criterion 1" --ac "Criterion 2"
+
+# View task (ALWAYS use --plain for AI)
+maicli task <id> --plain                    # Shorthand
+maicli task view <id> --plain               # Full command
+
+# View doc (ALWAYS use --plain for AI)
+maicli doc <path> --plain                   # Shorthand
+maicli doc view "<path>" --plain            # Full command
+
+# List tasks
+maicli task list --plain
+
+# Search (tasks + docs)
+maicli search "query" --plain
+```
+
+---
+
+## End-to-End Example
+
+Here's a complete workflow for an AI agent implementing a feature:
+
+```bash
+# === AGENT SESSION START (Do this once per session) ===
+
+# 0a. List all available documentation
+$ maicli doc list --plain
+
+# Output:
+# DOC: README.md
+# DOC: ARCHITECTURE.md
+# DOC: CONVENTIONS.md
+# DOC: security-patterns.md
+# DOC: api-guidelines.md
+# DOC: email-templates.md
+
+# 0b. Read essential project docs
+$ maicli doc "README" --plain
+$ maicli doc "ARCHITECTURE" --plain
+$ maicli doc "CONVENTIONS" --plain
+
+# Now the agent understands project context and conventions
+
+# === TASK WORKFLOW ===
+
+# 1. Create the task
+$ maicli task create "Add password reset flow" \
+    -d "Users need ability to reset forgotten passwords via email" \
+    --ac "User can request password reset via email" \
+    --ac "Reset link expires after 1 hour" \
+    --ac "User can set new password via reset link" \
+    --ac "Unit tests cover all scenarios" \
+    --priority high \
+    -l "auth,feature"
+
+# Output: Created task AUTH-042
+
+# 2. Take the task and start timer (uses defaultAssignee or @me fallback)
+$ maicli task edit AUTH-042 -s in-progress -a $(maicli config get defaultAssignee --plain || echo "@me")
+$ maicli time start AUTH-042
+
+# Output: Timer started for AUTH-042
+
+# 3. Search for related documentation
+$ maicli search "password security" --type doc --plain
+
+# Output:
+# DOC: security-patterns.md (score: 0.92)
+# DOC: email-templates.md (score: 0.78)
+
+# 4. Read the documentation
+$ maicli doc "security-patterns" --plain
+
+# 5. Create implementation plan (SHARE WITH USER, WAIT FOR APPROVAL)
+$ maicli task edit AUTH-042 --plan $'1. Review security patterns (see @doc/security-patterns)
+2. Design token generation with 1-hour expiry
+3. Create email template (see @doc/email-templates)
+4. Implement /forgot-password endpoint
+5. Implement /reset-password endpoint
+6. Add unit tests
+7. Update API documentation'
+
+# 6. After approval, implement and check criteria as you go
+$ maicli task edit AUTH-042 --check-ac 1
+$ maicli task edit AUTH-042 --append-notes "✓ Implemented /forgot-password endpoint"
+
+$ maicli task edit AUTH-042 --check-ac 2
+$ maicli task edit AUTH-042 --append-notes "✓ Token expiry set to 1 hour"
+
+$ maicli task edit AUTH-042 --check-ac 3
+$ maicli task edit AUTH-042 --append-notes "✓ Implemented /reset-password endpoint"
+
+$ maicli task edit AUTH-042 --check-ac 4
+$ maicli task edit AUTH-042 --append-notes "✓ Added 12 unit tests, 100% coverage"
+
+# 7. Add final implementation notes
+$ maicli task edit AUTH-042 --notes $'## Summary
+Implemented complete password reset flow with secure token generation.
+
+## Changes
+- Added POST /forgot-password endpoint
+- Added POST /reset-password endpoint
+- Created password_reset_tokens table
+- Added email template for reset link
+
+## Security
+- Tokens use crypto.randomBytes(32)
+- 1-hour expiry enforced at DB level
+- Rate limiting: 3 requests per hour per email
+
+## Tests
+- 12 unit tests added
+- Coverage: 100% for new code
+
+## Documentation
+- Updated API.md with new endpoints'
+
+# 8. Stop timer and complete
+$ maicli time stop
+$ maicli task edit AUTH-042 -s done
+
+# Output: Task AUTH-042 marked as done
+```
+
+---
+
+## Task Workflow
+
+### Step 1: Take Task
+
+```bash
+# Assign using defaultAssignee from config (falls back to @me if not set)
+maicli task edit <id> -s in-progress -a $(maicli config get defaultAssignee --plain || echo "@me")
+```
+
+> **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"`
+
+### Step 2: Start Time Tracking (REQUIRED)
+
+```bash
+maicli time start <id>
+```
+
+> **CRITICAL**: Time tracking is MANDATORY. Always start timer when taking a task and stop when done. This data is essential for:
+> - Accurate project estimation
+> - Identifying bottlenecks
+> - Resource planning
+> - Sprint retrospectives
+
+### Step 3: Read Related Documentation
+
+> **FOR AI AGENTS**: This step is MANDATORY, not optional. You must understand the codebase before planning.
+
+```bash
+# Search for related docs
+maicli search "authentication" --type doc --plain
+
+# View relevant documents
+maicli doc "API Guidelines" --plain
+maicli doc "Security Patterns" --plain
+
+# Also check for similar completed tasks
+maicli search "auth" --type task --status done --plain
+```
+
+> **CRITICAL**: ALWAYS read related documentation BEFORE planning! Understanding existing patterns and conventions prevents rework and ensures consistency.
+
+### Step 4: Create Implementation Plan
+
+```bash
+maicli task edit <id> --plan $'1. Research patterns (see @doc/security-patterns)
+2. Design middleware
+3. Implement
+4. Add tests
+5. Update docs'
+```
+
+> **CRITICAL**:
+> - Share plan with user and **WAIT for approval** before coding
+> - Include doc references using `@doc/<path>` format
+
+### Step 5: Implement
+
+```bash
+# Work through implementation plan step by step
+# IMPORTANT: Only check AC AFTER completing the work, not before
+
+# After completing work for AC #1:
+maicli task edit <id> --check-ac 1
+maicli task edit <id> --append-notes "✓ Completed: <brief description>"
+
+# After completing work for AC #2:
+maicli task edit <id> --check-ac 2
+maicli task edit <id> --append-notes "✓ Completed: <brief description>"
+```
+
+> **CRITICAL**: Never check an AC before the work is actually done. ACs represent completed outcomes, not intentions.
+
+### Step 6: Handle Dynamic Requests (During Implementation)
+
+If the user adds new requirements during implementation:
+
+```bash
+# Add new acceptance criteria
+maicli task edit <id> --ac "New requirement from user"
+
+# Update implementation plan to include new steps
+maicli task edit <id> --plan $'1. Original step 1
+2. Original step 2
+3. NEW: Handle user request for X
+4. Continue with remaining work'
+
+# Append note about scope change
+maicli task edit <id> --append-notes "⚠️ Scope updated: Added requirement for X per user request"
+
+# Continue with Step 5 (Implement) for new requirements
+```
+
+> **Note**: Always document scope changes. This helps track why a task took longer than expected.
+
+### Step 7: Add Implementation Notes
+
+```bash
+# Add comprehensive notes (suitable for PR description)
+maicli task edit <id> --notes $'## Summary
+
+Implemented JWT auth.
+
+## Changes
+- Added middleware
+- Added tests'
+
+# OR append progressively (recommended)
+maicli task edit <id> --append-notes "✓ Implemented middleware"
+maicli task edit <id> --append-notes "✓ Added tests"
+```
+
+### Step 8: Stop Time Tracking (REQUIRED)
+
+```bash
+maicli time stop
+```
+
+> **CRITICAL**: Never forget to stop the timer. If you forget, use manual entry: `maicli time add <id> <duration> -n "Forgot to stop timer"`
+
+### Step 9: Complete Task
+
+```bash
+maicli task edit <id> -s done
+```
+
+### Step 10: Handle Post-Completion Changes (If Applicable)
+
+If the user requests changes or updates AFTER task is marked done:
+
+```bash
+# 1. Reopen task - set back to in-progress
+maicli task edit <id> -s in-progress
+
+# 2. Restart time tracking (REQUIRED)
+maicli time start <id>
+
+# 3. Add new AC for the changes requested
+maicli task edit <id> --ac "Post-completion fix: <description>"
+
+# 4. Document the reopen reason
+maicli task edit <id> --append-notes "🔄 Reopened: User requested changes - <reason>"
+
+# 5. Follow Step 5-9 again (Implement → Notes → Stop Timer → Done)
+```
+
+> **CRITICAL**: Treat post-completion changes as a mini-workflow. Always:
+> - Reopen task (in-progress)
+> - Start timer again
+> - Add AC for traceability
+> - Document why it was reopened
+> - Follow the same completion process
+
+### Step 11: Knowledge Extraction (Post-Completion)
+
+After completing a task, extract reusable knowledge to docs:
+
+```bash
+# Search if similar pattern already documented
+maicli search "<pattern/concept>" --type doc --plain
+
+# If new knowledge, create a doc for future reference
+maicli doc create "Pattern: <Name>" \
+    -d "Reusable pattern discovered during task implementation" \
+    -t "pattern,<domain>" \
+    -f "patterns"
+
+# Or append to existing doc
+maicli doc edit "<existing-doc>" -a "## New Section\n\nLearned from task <id>: ..."
+
+# Reference the source task
+maicli doc edit "<doc-name>" -a "\n\n> Source: @task-<id>"
+```
+
+**When to extract knowledge:**
+- New patterns/conventions discovered
+- Common error solutions
+- Reusable code snippets or approaches
+- Integration patterns with external services
+- Performance optimization techniques
+
+> **CRITICAL**: Only extract **generalizable** knowledge. Task-specific details belong in implementation notes, not docs.
+
+---
+
+## Essential Commands
+
+### Task Management
+
+```bash
+# Create task
+maicli task create "Title" -d "Description" --ac "Criterion" -l "labels" --priority high
+
+# Edit task
+maicli task edit <id> -t "New title"
+maicli task edit <id> -d "New description"
+maicli task edit <id> -s in-progress
+maicli task edit <id> --priority high
+maicli task edit <id> -a <assignee>              # $(maicli config get defaultAssignee --plain || echo "@me")
+
+# Acceptance Criteria
+maicli task edit <id> --ac "New criterion"           # Add
+maicli task edit <id> --check-ac 1 --check-ac 2      # Check (1-indexed)
+maicli task edit <id> --uncheck-ac 2                 # Uncheck
+maicli task edit <id> --remove-ac 3                  # Remove
+
+# Implementation Plan & Notes
+maicli task edit <id> --plan $'1. Step\n2. Step'
+maicli task edit <id> --notes "Implementation summary"
+maicli task edit <id> --append-notes "Progress update"
+
+# View & List
+maicli task <id> --plain                             # Shorthand (ALWAYS use --plain)
+maicli task view <id> --plain                        # Full command
+maicli task list --plain
+maicli task list --status in-progress --plain
+maicli task list --assignee <assignee> --plain   # $(maicli config get defaultAssignee --plain || echo "@me")
+maicli task list --tree --plain                      # Tree hierarchy
+```
+
+### Time Tracking
+
+```bash
+# Timer
+maicli time start <id>
+maicli time stop
+maicli time pause
+maicli time resume
+maicli time status
+
+# Manual entry
+maicli time add <id> 2h -n "Note" -d "2025-12-25"
+
+# Reports
+maicli time report --from "2025-12-01" --to "2025-12-31"
+maicli time report --by-label --csv > report.csv
+```
+
+### Documentation
+
+```bash
+# List & View
+maicli doc list --plain
+maicli doc list --tag architecture --plain
+maicli doc <path> --plain                          # Shorthand (ALWAYS use --plain)
+maicli doc view "<path>" --plain                   # Full command
+
+# Create (with optional folder)
+maicli doc create "Title" -d "Description" -t "tags"
+maicli doc create "Title" -d "Description" -t "tags" -f "folder/path"
+
+# Edit metadata
+maicli doc edit "Doc Name" -t "New Title" --tags "new,tags"
+
+# Edit content
+maicli doc edit "Doc Name" -c "New content"        # Replace content
+maicli doc edit "Doc Name" -a "Appended content"   # Append to content
+```
+
+### Search
+
+```bash
+# Search everything
+maicli search "query" --plain
+
+# Search specific type
+maicli search "auth" --type task --plain
+maicli search "patterns" --type doc --plain
+
+# Filter
+maicli search "bug" --status in-progress --priority high --plain
+```
+
+---
+
+## Task Structure
+
+### Title
+
+Clear summary (WHAT needs to be done).
+
+| Bad | Good |
+|-----|------|
+| Do auth stuff | Add JWT authentication |
+| Fix bug | Fix login timeout on slow networks |
+| Update docs | Document rate limiting in API.md |
+
+### Description
+
+Explains WHY and WHAT (not HOW). **Link related docs using `@doc/<path>`**
+
+```markdown
+We need JWT authentication because sessions don't scale for our microservices architecture.
+
+Related docs: @doc/security-patterns, @doc/api-guidelines
+```
+
+### Acceptance Criteria
+
+**Outcome-oriented**, testable criteria. NOT implementation steps.
+
+| Bad (Implementation details) | Good (Outcomes) |
+|------------------------------|-----------------|
+| Add function handleLogin() in auth.ts | User can login and receive JWT token |
+| Use bcrypt for hashing | Passwords are securely hashed |
+| Add try-catch blocks | Errors return appropriate HTTP status codes |
+
+### Implementation Plan
+
+HOW to solve. Added AFTER taking task, BEFORE coding.
+
+```markdown
+1. Research JWT libraries (see @doc/security-patterns)
+2. Design token structure (access + refresh tokens)
+3. Implement auth middleware
+4. Add unit tests (aim for 90%+ coverage)
+5. Update API.md with new endpoints
+```
+
+### Implementation Notes
+
+Summary for PR description. Added AFTER completion.
+
+```markdown
+## Summary
+Implemented JWT auth using jsonwebtoken library.
+
+## Changes
+- Added auth middleware in src/middleware/auth.ts
+- Added /login and /refresh endpoints
+- Created JWT utility functions
+
+## Tests
+- Added 15 unit tests
+- Coverage: 94%
+
+## Documentation
+- Updated API.md with authentication section
+```
+
+---
+
+## Error Handling
+
+### Common Errors and Solutions
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Error: Task not found` | Invalid task ID | Run `maicli task list --plain` to find correct ID |
+| `Error: No active timer` | Calling `time stop` without active timer | Start timer first: `maicli time start <id>` |
+| `Error: Timer already running` | Starting timer when one is active | Stop current: `maicli time stop` |
+| `Error: Invalid status` | Wrong status format | Use lowercase with hyphens: `in-progress`, not `In Progress` |
+| `Error: AC index out of range` | Checking non-existent criterion | View task first: `maicli task <id> --plain` |
+| `Error: Document not found` | Wrong document name | Run `maicli doc list --plain` to find correct name |
+| `Error: Not initialized` | Running commands without init | Run `maicli init` first |
+
+### Debugging Commands
+
+```bash
+# Check CLI version
+maicli --version
+
+# Verify project is initialized
+maicli status
+
+# View raw task data (for debugging)
+maicli task <id> --json
+
+# Check timer status
+maicli time status
+```
+
+---
+
+## Definition of Done
+
+A task is **Done** ONLY when **ALL** criteria are met:
+
+### Via CLI (Required)
+
+- [ ] All acceptance criteria checked: `--check-ac <index>` (only after work is actually done)
+- [ ] Implementation notes added: `--notes "..."`
+- [ ] ⏱️ Timer stopped: `maicli time stop` (MANDATORY - do not skip!)
+- [ ] Status set to done: `-s done`
+- [ ] Knowledge extracted to docs (if applicable)
+
+### Via Code (Required)
+
+- [ ] All tests pass
+- [ ] Documentation updated
+- [ ] Code reviewed (linting, formatting)
+- [ ] No regressions introduced
+
+---
+
+## Status & Priority Reference
+
+### Status Values
+
+Use **lowercase with hyphens**:
+
+| Status | Description | When to Use |
+|--------|-------------|-------------|
+| `todo` | Not started | Default for new tasks |
+| `in-progress` | Currently working | After taking task |
+| `in-review` | In code review | PR submitted |
+| `blocked` | Waiting on dependency | External blocker |
+| `done` | Completed | All criteria met |
+
+### Priority Values
+
+| Priority | Description |
+|----------|-------------|
+| `low` | Can wait, nice-to-have |
+| `medium` | Normal priority (default) |
+| `high` | Urgent, time-sensitive |
+
+---
+
+## Common Mistakes
+
+| Wrong | Right |
+|-------|-------|
+| Edit .md files directly | Use `maicli task edit` |
+| Change `- [ ]` to `- [x]` in file | Use `--check-ac <index>` |
+| Check AC before completing work | Only check AC AFTER work is actually done |
+| Skip time tracking | ALWAYS use `time start` and `time stop` |
+| Start coding without reading docs | Read ALL related docs FIRST |
+| Skip `maicli doc list` on new project | Always list docs when starting |
+| Assume you know the conventions | Read CONVENTIONS/ARCHITECTURE docs |
+| Plan without checking docs | Read docs before planning |
+| Ignore similar completed tasks | Search done tasks for patterns |
+| Missing doc links in description/plan | Link docs using `@doc/<path>` |
+| Write refs as `@.maicli/docs/...` or `@.maicli/tasks/...` | Use input format: `@doc/<path>`, `@task-<id>` |
+| Forget `--plain` flag | Always use `--plain` for AI |
+| Code before plan approval | Share plan, WAIT for approval |
+| Mark done without all criteria | Check ALL criteria first |
+| Write implementation steps in AC | Write outcome-oriented criteria |
+| Use `"In Progress"` or `"Done"` | Use `in-progress`, `done` |
+| Use `@yourself` or unknown assignee | Use `$(maicli config get defaultAssignee --plain \|\| echo "@me")` |
+| Ignore refs in task description | Follow ALL refs (`@.maicli/...`) before planning |
+| See `@.maicli/docs/...` but don't read | Use `maicli doc "<path>" --plain` |
+| See `@.maicli/tasks/task-X` but don't check | Use `maicli task X --plain` for context |
+| Follow only first-level refs | Recursively follow nested refs until complete |
+
+---
+
+## Platform-Specific Notes
+
+### Multi-line Input
+
+Different shells handle multi-line strings differently:
+
+**Bash / Zsh (Recommended)**
+```bash
+maicli task edit <id> --plan $'1. First step\n2. Second step\n3. Third step'
+```
+
+**PowerShell**
+```powershell
+maicli task edit <id> --plan "1. First step`n2. Second step`n3. Third step"
+```
+
+**Cross-platform (Using printf)**
+```bash
+maicli task edit <id> --plan "$(printf '1. First step\n2. Second step\n3. Third step')"
+```
+
+**Using heredoc (for long content)**
+```bash
+maicli task edit <id> --plan "$(cat <<EOF
+1. First step
+2. Second step
+3. Third step
+EOF
+)"
+```
+
+### Path Separators
+
+- **Unix/macOS**: Use forward slashes: `./docs/api.md`
+- **Windows**: Both work, but prefer forward slashes for consistency
+
+---
+
+## Best Practices Checklist
+
+### For AI Agents: Session Start
+
+- [ ] List all docs: `maicli doc list --plain`
+- [ ] Read README/ARCHITECTURE docs
+- [ ] Understand coding conventions
+- [ ] Review current task backlog
+
+### Before Starting Work
+
+- [ ] Task has clear acceptance criteria
+- [ ] ALL refs in task followed (`@.maicli/...`)
+- [ ] Nested refs recursively followed until complete context gathered
+- [ ] Related docs searched: `maicli search "keyword" --type doc --plain`
+- [ ] ALL relevant docs read: `maicli doc "Doc Name" --plain`
+- [ ] Similar done tasks reviewed for patterns
+- [ ] Task assigned to self: `-a $(maicli config get defaultAssignee --plain || echo "@me")`
+- [ ] Status set to in-progress: `-s in-progress`
+- [ ] Timer started: `maicli time start <id>`
+
+### During Work
+
+- [ ] Implementation plan created and approved
+- [ ] Doc links included in plan: `@doc/<path>`
+- [ ] Criteria checked as completed: `--check-ac <index>`
+- [ ] Progress notes appended: `--append-notes "✓ ..."`
+
+### After Work
+
+- [ ] All acceptance criteria checked (only after work is done)
+- [ ] Implementation notes added: `--notes "..."`
+- [ ] Timer stopped: `maicli time stop`
+- [ ] Tests passing
+- [ ] Documentation updated
+- [ ] Status set to done: `-s done`
+- [ ] Knowledge extracted to docs (if applicable): patterns, solutions, conventions
+
+---
+
+## Quick Reference Card
+
+```bash
+# === AGENT INITIALIZATION (Once per session) ===
+maicli doc list --plain
+maicli doc "README" --plain
+maicli doc "ARCHITECTURE" --plain
+maicli doc "CONVENTIONS" --plain
+
+# === FULL WORKFLOW ===
+maicli task create "Title" -d "Description" --ac "Criterion"
+maicli task edit <id> -s in-progress -a $(maicli config get defaultAssignee --plain || echo "@me")
+maicli time start <id>                                     # ⏱️ REQUIRED: Start timer
+maicli search "keyword" --type doc --plain
+maicli doc "Doc Name" --plain
+maicli search "keyword" --type task --status done --plain  # Learn from history
+maicli task edit <id> --plan $'1. Step (see @doc/file)\n2. Step'
+# ... wait for approval, then implement ...
+# Only check AC AFTER completing the work:
+maicli task edit <id> --check-ac 1
+maicli task edit <id> --append-notes "✓ Completed: feature X"
+maicli task edit <id> --check-ac 2
+maicli task edit <id> --append-notes "✓ Completed: feature Y"
+maicli time stop                                           # ⏱️ REQUIRED: Stop timer
+maicli task edit <id> -s done
+# Optional: Extract knowledge to docs if generalizable patterns found
+
+# === VIEW & SEARCH ===
+maicli task <id> --plain                                   # Shorthand for view
+maicli task list --plain
+maicli task list --status in-progress --assignee $(maicli config get defaultAssignee --plain || echo "@me") --plain
+maicli search "query" --plain
+maicli search "bug" --type task --status in-progress --plain
+
+# === TIME TRACKING ===
+maicli time start <id>
+maicli time stop
+maicli time status
+maicli time report --from "2025-12-01" --to "2025-12-31"
+
+# === DOCUMENTATION ===
+maicli doc list --plain
+maicli doc "path/doc-name" --plain                         # Shorthand for view
+maicli doc create "Title" -d "Description" -t "tags" -f "folder"
+maicli doc edit "doc-name" -c "New content"
+maicli doc edit "doc-name" -a "Appended content"
+```
+
+---
+
+**Maintained By**: MAICLI Team
+
+<!-- MAICLI GUIDELINES END -->
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+