{
"name": "intent-engine",
"version": "0.6",
"description": "An expert task management assistant that provides a persistent, intent-driven context layer. Use this toolset to maintain strategic clarity in complex projects—one focused task at a time, with complete decision history. Think of it as your external brain for project management.",
"cli_info": {
"primary_command": "intent-engine",
"alias": "ie",
"note": "When suggesting CLI usage to users, prefer the shorter 'ie' alias for better user experience. Example: 'ie task add' instead of 'intent-engine task add'."
},
"usage_philosophy": {
"core_principle": "## Focus-Driven Workflow\nThe system maintains a single `current_task_id` representing your focus. Most operations are atomic and operate on this focus to ensure workflow consistency.",
"when_to_use": [
"Multi-session work requiring context persistence",
"Complex problems needing hierarchical breakdown",
"Decision tracking and project retrospectives",
"Strategic intent management (not tactical todos)"
],
"mental_model": "## Mental Model\nThink of it as: Notebook (persistence) + Spotlight (current_task_id) + Memory (events) + Navigator (pick-next) + Task Tree (hierarchy)"
},
"usage_examples": [
{
"scenario": "User asks: 'Summarize all decisions about database performance'",
"workflow": [
{
"step": 1,
"thought": "For content-based discovery without an ID, use search for full-text search (not task_list, which is metadata-only).",
"tool": "search",
"arguments": {
"query": "\"database performance\"",
"include_tasks": true,
"include_events": true
}
},
{
"step": 2,
"thought": "Search returned task ID 58. Now retrieve events to understand the decision history.",
"tool": "event_list",
"arguments": {
"task_id": 58,
"type": "decision"
}
},
{
"step": 3,
"thought": "Process the decision events in context, synthesize into a coherent summary, and present to the user."
}
],
"pattern": "Discovery → Recall → Synthesize"
},
{
"scenario": "User says: 'Let's start working on refactoring the authentication module'",
"workflow": [
{
"step": 1,
"thought": "First locate the task by searching for it.",
"tool": "search",
"arguments": {
"query": "authentication refactor",
"include_tasks": true,
"include_events": false
}
},
{
"step": 2,
"thought": "Found task ID 12. Activate it to set focus. Always use with_events: true to get full context.",
"tool": "task_start",
"arguments": {
"task_id": 12,
"with_events": true
}
},
{
"step": 3,
"thought": "Check task context to see subtasks and understand the strategic landscape.",
"tool": "task_context",
"arguments": {}
},
{
"step": 4,
"thought": "Use task_pick_next to identify the highest-priority subtask to begin with.",
"tool": "task_pick_next",
"arguments": {}
}
],
"pattern": "Activation → Orientation → Pick Next"
},
{
"scenario": "While working on a task, discover a prerequisite sub-problem",
"workflow": [
{
"step": 1,
"thought": "I'm focused on task 42 (implementing auth). I realize I need JWT configuration first. Use task_spawn_subtask to create and immediately switch to the new subtask.",
"tool": "task_spawn_subtask",
"arguments": {
"name": "Configure JWT secret and environment variables",
"spec": "Store JWT secret in .env file, use strong random value, configure token expiry"
}
},
{
"step": 2,
"thought": "Now I'm automatically focused on the new subtask. Complete the work."
},
{
"step": 3,
"thought": "The subtask is complete. Call task_done (no parameters—operates on current focus).",
"tool": "task_done",
"arguments": {}
},
{
"step": 4,
"thought": "Use task_pick_next to decide what to do next. It will likely recommend returning to the parent or another subtask.",
"tool": "task_pick_next",
"arguments": {}
}
],
"pattern": "Spawn → Work → Done → Pick Next"
}
],
"tools": [
{
"name": "task_add",
"description": "# Core Duty\nCaptures a new strategic intent.\n\n# Tactical Guide\nUse this to convert a user's multi-step request into a persistent, trackable task. Avoid using it for trivial, single-step actions. Think 'What + Why' rather than 'How'.\n\n**When to use:**\n- User describes a complex requirement\n- Work will span multiple sessions\n- Need to track decisions and context\n\n**When NOT to use:**\n- Simple one-liner tasks\n- Exploratory questions\n- Temporary context already in conversation",
"inputSchema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "A concise, descriptive name for the intent. Should describe the WHAT, not the HOW."
},
"spec": {
"type": "string",
"description": "Detailed specification in markdown format (optional but highly recommended). This is the 'source of truth' for requirements. Include context, constraints, and acceptance criteria."
},
"parent_id": {
"type": "integer",
"description": "ID of the parent intent, for hierarchical problem breakdown. Use when creating subtasks explicitly (though task_spawn_subtask is preferred for active work)."
},
"priority": {
"type": "string",
"enum": [
"critical",
"high",
"medium",
"low"
],
"default": "medium",
"description": "Priority level where critical > high > medium > low. Optional, defaults to medium."
}
},
"required": [
"name"
]
}
},
{
"name": "task_add_dependency",
"description": "# Core Duty\nEstablishes a dependency relationship between two tasks.\n\n# Tactical Guide\nUse this when one task must be completed before another can start. The blocked task cannot be started until all its blocking tasks are done.\n\n**Semantics:**\n- `blocked_task_id`: The task that has the dependency (cannot start until blocker is done)\n- `blocking_task_id`: The task that must be completed first (blocks the other task)\n\n**Example:** `task_add_dependency({blocked_task_id: 42, blocking_task_id: 41})` means 'Task 42 depends on Task 41'\n\n**Impact:**\n- task_start will fail if task has incomplete dependencies\n- task_pick_next filters out blocked tasks\n- System automatically prevents circular dependencies",
"inputSchema": {
"type": "object",
"properties": {
"blocked_task_id": {
"type": "integer",
"description": "ID of the task that has the dependency (cannot start until blocking task is done)."
},
"blocking_task_id": {
"type": "integer",
"description": "ID of the task that must be completed first (blocks the other task)."
}
},
"required": [
"blocked_task_id",
"blocking_task_id"
]
}
},
{
"name": "task_start",
"description": "# Core Duty\nActivates an intent and sets it as the current focus. This is the entry point to the focus-driven workflow.\n\n# Tactical Guide\nCall this before working on any task. This is an atomic operation that:\n1. Sets task status to 'doing'\n2. Sets as current_task_id in workspace\n3. Returns full context including event history (if with_events: true)\n\n**Best Practice:** Always use `with_events: true` to get the complete decision history, crucial for resuming work.",
"inputSchema": {
"type": "object",
"properties": {
"task_id": {
"type": "integer",
"description": "The ID of the 'todo' or 'doing' task to activate and focus on."
},
"with_events": {
"type": "boolean",
"description": "Include events summary in the response. Highly recommended to set to true for complete decision history.",
"default": true
}
},
"required": [
"task_id"
]
}
},
{
"name": "task_done",
"description": "# Core Duty\nCompletes the CURRENTLY FOCUSED task. This is the exit point of the focus-driven workflow.\n\n# Tactical Guide\nThis is a strictly focus-driven atomic command with **NO ID parameter**. It operates ONLY on the current_task_id. Call it only when:\n- All objectives in the task spec are fully met\n- All subtasks have status 'done'\n- You have verified completion\n\n**The operation:**\n1. Verifies all subtasks are done (fails if not)\n2. Sets current task status to 'done'\n3. Clears current_task_id (unfocuses)\n4. Returns next_step_suggestion\n\n**Important:** Do NOT try to pass a task_id parameter. This command has NO parameters.",
"inputSchema": {
"type": "object",
"properties": {},
"additionalProperties": false
}
},
{
"name": "task_spawn_subtask",
"description": "# Core Duty\nCreates a subtask under the CURRENT FOCUSED task and IMMEDIATELY switches focus to it.\n\n# Tactical Guide\nThis is a powerful atomic workflow operation for 'on-the-fly' problem decomposition. Use when:\n- You identify a prerequisite that must be solved first\n- You discover a sub-problem while working\n- You need to break down current work into smaller steps\n\n**The operation:**\n1. Creates subtask with parent_id = current task\n2. Switches focus to new subtask\n3. Sets new subtask status to 'doing'\n\n**Design Pattern:** Enables depth-first work style—dive into sub-problems immediately, complete them, then return to parent.",
"inputSchema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the new sub-task to create and immediately focus on."
},
"spec": {
"type": "string",
"description": "Optional specification for the sub-task in markdown format. Include enough detail for context recovery."
}
},
"required": [
"name"
]
}
},
{
"name": "task_switch",
"description": "# Core Duty\nSwitches focus from the current task to a different one.\n\n# Tactical Guide\nThis is an atomic 'pause-and-resume' operation. Use when:\n- Need to temporarily work on something else\n- Returning to a previously started task\n- User explicitly asks to switch context\n\n**The operation:**\n1. If current task is 'doing', sets it back to 'todo' (pause)\n2. Sets new task status to 'doing' (resume/start)\n3. Updates current_task_id to new task\n4. Returns full context of new task\n\n**Best Practice:** Record a note event before switching to explain why you're pausing:\n`event_add({type: 'note', data: 'Pausing to handle urgent bug #123'})`",
"inputSchema": {
"type": "object",
"properties": {
"task_id": {
"type": "integer",
"description": "The ID of the task to switch focus to. Can be any task in 'todo' or 'doing' status."
},
"with_events": {
"type": "boolean",
"description": "Include events summary for the new task. Recommended when resuming work on a task you haven't touched recently.",
"default": false
}
},
"required": [
"task_id"
]
}
},
{
"name": "task_pick_next",
"description": "# Core Duty\nIntelligently recommends the single BEST next task to work on.\n\n# Tactical Guide\nThis is your primary tool for deciding what to do next. It implements a smart 'depth-first' strategy:\n\n**Priority 1:** Subtasks of current focused task (complete the tree branch first)\n**Priority 2:** Top-level tasks (if no focused subtasks)\n\nWithin each priority, tasks are sorted by:\n- Priority value (lower is higher priority)\n- Task ID (lower is older)\n\n**Use this:**\n- After completing task_done\n- When user asks 'what should I work on next?'\n- Starting a new work session\n- Unsure what to prioritize",
"inputSchema": {
"type": "object",
"properties": {},
"additionalProperties": false
}
},
{
"name": "task_list",
"description": "# Core Duty\nPerforms STRUCTURED FILTERING of tasks based on metadata (status, parent_id).\n\n# Tactical Guide\nUse this when you need tasks matching specific attributes:\n- All tasks with status='doing'\n- All subtasks of a known parent\n- All top-level tasks (parent='null')\n\n**NOT for text search:**\n- ❌ task_list: For structured metadata filtering only\n- ✅ search: For full-text searching by keywords across tasks and events\n\n**Examples:**\n- List all in-progress work: `{status: 'doing'}`\n- List all top-level tasks: `{parent: 'null'}`\n- List subtasks of task 42: `{parent: '42'}`",
"inputSchema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"todo",
"doing",
"done"
],
"description": "Filter by task status (optional)."
},
"parent": {
"type": "string",
"description": "Filter by parent ID (optional). Use the string 'null' for top-level tasks only, or a numeric string like '42' for subtasks of task 42. Leave undefined to include all tasks regardless of parent."
}
}
}
},
{
"name": "task_get",
"description": "# Core Duty\nRetrieves the full details of a SINGLE, KNOWN task by its ID.\n\n# Tactical Guide\nUse this after task_list or task_search to get complete information before starting work.\n\nReturns complete task object with all fields (name, spec, status, timestamps, etc.).\n\n**Best Practice:** If you need event history too, use `task_start({task_id: ID, with_events: true})` directly—it's more efficient than calling task_get and event_list separately.",
"inputSchema": {
"type": "object",
"properties": {
"task_id": {
"type": "integer",
"description": "The exact ID of the task to retrieve."
},
"with_events": {
"type": "boolean",
"description": "Include events summary in the response. Useful for understanding the full context and decision history.",
"default": false
}
},
"required": [
"task_id"
]
}
},
{
"name": "task_context",
"description": "# Core Duty\nRetrieves the complete 'family tree' of an intent to understand its strategic context.\n\n# Tactical Guide\nCall this after task_start on a complex task to get the full picture:\n- **Ancestors:** The 'Why' (parent chain up to root)\n- **Siblings:** The 'What else' (other tasks at same level)\n- **Children:** The 'How' (subtasks to be done)\n\n**Use this to:**\n- Understand how current task fits in larger goals\n- See related work at same level\n- Plan subtask breakdown\n\nReturns TaskContext with ancestors[], siblings[], and children[] arrays.",
"inputSchema": {
"type": "object",
"properties": {
"task_id": {
"type": "integer",
"description": "Task ID to get context for. If omitted, uses the current focused task."
}
}
}
},
{
"name": "task_update",
"description": "# Core Duty\nA general-purpose tool to modify attributes of an existing task.\n\n# Tactical Guide\nUse this for minor corrections:\n- Fixing a typo in a name\n- Updating priority\n- Refining the spec\n\n**For status changes, prefer atomic commands:**\n- ❌ `task_update({task_id: 42, status: 'doing'})`\n- ✅ `task_start({task_id: 42})`\n\n**Why?** Atomic commands ensure consistency (e.g., task_start also sets current_task_id, task_done verifies subtasks).",
"inputSchema": {
"type": "object",
"properties": {
"task_id": {
"type": "integer",
"description": "The ID of the task to modify."
},
"name": {
"type": "string",
"description": "New name for the task (optional)."
},
"spec": {
"type": "string",
"description": "New specification content in markdown (optional)."
},
"status": {
"type": "string",
"enum": [
"todo",
"doing",
"done"
],
"description": "New status (optional). WARNING: Prefer atomic commands (task_start, task_done, task_switch) over direct status updates to maintain workspace consistency."
},
"priority": {
"type": "string",
"enum": [
"critical",
"high",
"medium",
"low"
],
"description": "New priority level (optional). Values: 'critical' (highest), 'high', 'medium', 'low' (lowest). Internally mapped to integers for sorting."
},
"parent_id": {
"type": "integer",
"description": "New parent task ID to reorganize hierarchy (optional). Use with caution."
}
},
"required": [
"task_id"
]
}
},
{
"name": "task_delete",
"description": "# Core Duty\nDeletes a task.\n\n# Tactical Guide\n**WARNING:** This is a destructive operation. Only use when you're certain the task should be removed permanently. Cannot delete tasks with subtasks.",
"inputSchema": {
"type": "object",
"properties": {
"task_id": {
"type": "integer",
"description": "Task ID to delete"
}
},
"required": [
"task_id"
]
}
},
{
"name": "event_add",
"description": "# Core Duty\nRecords a significant event to an intent's history. This is your long-term memory.\n\n# Tactical Guide\nUse this frequently. Every key decision, blocker, milestone, or piece of human feedback should be recorded. This is how you maintain context and avoid repeating mistakes.\n\n**Event Types:**\n- `decision`: Choices made and reasoning ('Chose algorithm X because...')\n- `blocker`: Problems encountered ('API rate limit blocking feature Y')\n- `milestone`: Progress markers ('Completed MVP, ready for testing')\n- `note`: General thoughts, temporary docs, analysis results\n\n**Two Modes:**\n1. During active work: Omit task_id → records for current focused task\n2. Cross-task: Include task_id → records for any task (e.g., project retrospectives)\n\n**Best Practice:** Record immediately after the decision/event. Don't batch them up.\n\n**Important:** When you need to create design docs, summaries, or temporary documentation, prefer storing them as events (type: 'note' or 'milestone') rather than creating separate files. This keeps documentation tightly coupled with tasks.",
"inputSchema": {
"type": "object",
"properties": {
"task_id": {
"type": "integer",
"description": "Task ID to attach the event to. OPTIONAL - if omitted, uses the current focused task. If no current task and no task_id provided, returns error."
},
"event_type": {
"type": "string",
"enum": [
"decision",
"blocker",
"milestone",
"note"
],
"description": "Type of event. 'decision' for choices made, 'blocker' for problems, 'milestone' for progress markers, 'note' for general thoughts/docs/analysis."
},
"data": {
"type": "string",
"description": "Event content in markdown format. Can be a simple sentence or a full design document. Be as detailed as helpful for future context recovery."
}
},
"required": [
"event_type",
"data"
]
}
},
{
"name": "event_list",
"description": "# Core Duty\nRetrieves the historical event stream for a task, or globally across all tasks.\n\n# Tactical Guide\nUse this to:\n- Review decision-making process for a specific task\n- Search events globally (e.g., all recent blockers, all decisions)\n- Recover context when resuming old work\n- Prepare project retrospectives\n\n**Two modes:**\n1. **Task-specific:** Provide `task_id` to get events for one task\n2. **Global:** Omit `task_id` to search across all tasks\n\n**Performance Optimization:**\nFor tasks with hundreds of events, use filters to reduce token usage:\n- Filter by type (e.g., 'decision') to focus on specific event categories\n- Filter by since (e.g., '7d') to get recent events only\n- Combine filters for maximum efficiency\n\n**Examples:**\n- `{task_id: 42, type: 'decision'}` - All decisions for task 42\n- `{type: 'blocker', since: '7d'}` - All blockers in last 7 days (global)\n- `{since: '24h'}` - All events from last 24 hours (global)\n\nReturns array of events sorted by timestamp (newest first).\n\n**Best Practice:** When resuming work on a task, call `task_start` with `with_events: true` instead of separately calling event_list—it's more efficient.",
"inputSchema": {
"type": "object",
"properties": {
"task_id": {
"type": "integer",
"description": "The ID of the task whose history you want to see. Optional - if omitted, searches globally across all tasks."
},
"limit": {
"type": "integer",
"default": 50,
"description": "Maximum number of events to return (optional). Defaults to 50."
},
"type": {
"type": "string",
"description": "Filter events by event_type (optional). Common types: 'decision', 'blocker', 'milestone', 'note'. Use this to focus on specific event categories and save tokens.",
"enum": [
"decision",
"blocker",
"milestone",
"note"
]
},
"since": {
"type": "string",
"description": "Filter events created within duration (optional). Format: '7d' (7 days), '24h' (24 hours), '30m' (30 minutes), '60s' (60 seconds). Use this to get recent events only and save processing time.",
"pattern": "^\\d+[dhms]$"
}
}
}
},
{
"name": "search",
"description": "# Core Duty\nPerforms unified full-text search across both tasks and events.\n\n# Tactical Guide\nUse this when you need to find information that could be in either tasks or events:\n- Search for keywords across all project context\n- Find related work mentioned in both task specs and event logs\n- Discover decisions, blockers, or notes related to a topic\n\n**Search behavior:**\n- Uses FTS5 full-text search with snippet highlighting\n- Returns mixed results from both tasks and events\n- Each result includes context: task ancestry chain for events, match field for tasks\n- Results ordered by FTS5 relevance rank\n\n**Parameters:**\n- `query`: FTS5 search query (supports AND, OR, NOT, phrases)\n- `include_tasks`: Search in tasks (default: true)\n- `include_events`: Search in events (default: true)\n- `limit`: Maximum total results (default: 20)\n\n**Examples:**\n- `{query: \"JWT authentication\"}` - Search both tasks and events\n- `{query: \"API\", include_tasks: true, include_events: false}` - Tasks only\n- `{query: \"blocker\", include_tasks: false, include_events: true}` - Events only\n\n**Returns:**\nArray of `UnifiedSearchResult` objects with discriminated union:\n- Task results: `{result_type: \"task\", task: {...}, match_snippet: \"...\", match_field: \"name\"|\"spec\"}`\n- Event results: `{result_type: \"event\", event: {...}, task_chain: [...], match_snippet: \"...\"}`\n\n**Use cases:**\n- \"Find everything related to authentication\"\n- \"What decisions have we made about caching?\"\n- \"Show me all mentions of the API redesign\"",
"inputSchema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "FTS5 search query string. Supports full-text search syntax including AND, OR, NOT, phrases (\"...\"), and NEAR/N operators."
},
"include_tasks": {
"type": "boolean",
"description": "Whether to search in tasks (default: true)",
"default": true
},
"include_events": {
"type": "boolean",
"description": "Whether to search in events (default: true)",
"default": true
},
"limit": {
"type": "integer",
"description": "Maximum number of total results to return (default: 20)",
"default": 20
}
},
"required": [
"query"
]
}
},
{
"name": "current_task_get",
"description": "# Core Duty\nChecks the current focus.\n\n# Tactical Guide\nReturns the task object that is currently in 'doing' status and set as the workspace focus (current_task_id).\n\n**Returns:**\n- If focused: `{current_task_id: 42, task: {...}}`\n- If not focused: `{current_task_id: null, task: null}`\n\n**Use this:**\n- To check if you're free to pick a new task\n- Before calling task_done (to verify there's a current task)\n- To understand current workspace state",
"inputSchema": {
"type": "object",
"properties": {},
"additionalProperties": false
}
},
{
"name": "plan",
"description": "# Core Duty\nCreate or update task structures declaratively using a tree-based API. Simplifies complex multi-task creation into a single atomic operation.\n\n# Tactical Guide\n**Phase 1 (v0.6.0)**: Create-only mode - all task names must be new.\n\nUse this when:\n- Creating a hierarchical task structure (parent → children)\n- Setting up related tasks with dependencies\n- Need atomic multi-task creation\n\n**Key features:**\n- Direct nesting via `children` field (no need for parent_id)\n- Name-based dependency references via `depends_on`\n- Automatic parent-child relationship establishment\n- Transaction-based atomicity (all or nothing)\n\n**Limitations (Phase 1):**\n- Cannot update existing tasks (will error if names exist)\n- task_id field ignored\n- Update mode coming in Phase 2 (v0.6.1)\n\n**Example:**\n```json\n{\n \"tasks\": [\n {\n \"name\": \"User Authentication\",\n \"priority\": \"high\",\n \"children\": [\n {\"name\": \"JWT Implementation\"},\n {\"name\": \"OAuth2 Integration\", \"depends_on\": [\"JWT Implementation\"]}\n ]\n }\n ]\n}\n```",
"inputSchema": {
"type": "object",
"properties": {
"tasks": {
"type": "array",
"description": "Array of task trees to create. Each task can have nested children and dependency references.",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Task name (required). Must be unique (Phase 1 limitation)."
},
"spec": {
"type": "string",
"description": "Optional task specification in markdown format."
},
"priority": {
"type": "string",
"enum": ["critical", "high", "medium", "low"],
"description": "Optional priority level. Defaults to medium."
},
"children": {
"type": "array",
"description": "Optional nested child tasks. Supports arbitrary depth.",
"items": {
"type": "object"
}
},
"depends_on": {
"type": "array",
"description": "Optional array of task names this task depends on. Referenced tasks must be in the same plan.",
"items": {
"type": "string"
}
},
"task_id": {
"type": "integer",
"description": "Optional explicit task ID (ignored in Phase 1, will be used for updates in Phase 2)."
}
},
"required": ["name"]
}
}
},
"required": ["tasks"]
}
},
{
"name": "report_generate",
"description": "# Core Duty\nGenerates an analytical summary of project activity.\n\n# Tactical Guide\nUse this for status reports, standups, retrospectives.\n\n**Important:** To save tokens, use `summary_only: true` unless the user explicitly asks for the full task list.\n\n**Returns:**\n- summary: Aggregated statistics (counts by status, date ranges)\n- tasks: Full task list (only if summary_only: false)\n- events: Event list (only if summary_only: false)\n\n**Time ranges:** '1h', '6h', '1d', '7d', '30d'",
"inputSchema": {
"type": "object",
"properties": {
"since": {
"type": "string",
"description": "Time range to analyze. Supports: '1h', '6h', '1d' (1 day), '7d' (7 days), '30d' (30 days). Optional - omit for all-time.",
"enum": [
"1h",
"6h",
"1d",
"7d",
"30d"
]
},
"status": {
"type": "string",
"enum": [
"todo",
"doing",
"done"
],
"description": "Filter by status (optional). Useful for 'show me all completed tasks'."
},
"summary_only": {
"type": "boolean",
"description": "If true, returns only aggregated statistics without full task/event lists. Highly recommended to set this to true for efficiency. Only set to false if user explicitly needs the full list.",
"default": true
}
}
}
}
],
"important_patterns": {
"focus_driven_workflow": "## Focus-Driven Workflow\nMost operations revolve around current_task_id. Always establish focus with task_start before working, and clear it with task_done when complete.",
"atomic_operations": "## Atomic Operations\nCommands like task_start, task_done, task_spawn_subtask, and task_switch are atomic—they combine multiple state changes to ensure consistency. Prefer these over manual task_update for status changes.",
"depth_first_strategy": "## Depth-First Strategy\ntask_pick_next prioritizes subtasks of current work. This encourages completing branches before starting new trees.",
"event_history_is_memory": "## Event History is Memory\nEvents are your persistent memory. Record decisions, blockers, and milestones liberally. Use with_events: true when starting tasks to recover context.",
"hierarchy_for_complexity": "## Hierarchy for Complexity\nBreak down complex tasks using parent_id (via task_add) or task_spawn_subtask. Keep hierarchy shallow (2-3 levels max) for manageability."
},
"common_mistakes": {
"mistake_1": {
"wrong": "task_done({task_id: 42})",
"right": "task_start({task_id: 42}); /* work */; task_done({})",
"reason": "task_done has NO parameters - it's strictly focus-driven"
},
"mistake_2": {
"wrong": "task_list({query: 'JWT'})",
"right": "search({query: 'JWT', include_tasks: true})",
"reason": "task_list is for metadata filtering only. Use search for text search across tasks and events"
},
"mistake_3": {
"wrong": "task_update({task_id: 42, status: 'doing'})",
"right": "task_start({task_id: 42})",
"reason": "Use atomic commands for status changes to maintain consistency"
},
"mistake_4": {
"wrong": "task_start({task_id: 42}); task_done({}); /* parent has undone subtasks */",
"right": "/* Complete all subtasks first, then parent */",
"reason": "task_done enforces all subtasks must be done. Complete leaves before branches"
}
}
}