Initial commit

.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "reclaim",
+  "description": "CRUD operations for Reclaim.ai tasks including create, update, list, complete, and delete with confirmation workflow",
+  "version": "0.0.0-2025.11.28",
+  "author": {
+    "name": "Benjamin Jackson",
+    "email": "ben@hearmeout.co"
+  },
+  "skills": [
+    "./skills/reclaim-tasks"
+  ]
+}

README.md

@@ -0,0 +1,3 @@
+# reclaim
+
+CRUD operations for Reclaim.ai tasks including create, update, list, complete, and delete with confirmation workflow

plugin.lock.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:benjaminjackson/reclaim-skills:reclaim",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "a90be289f4ce85ff6b2eb8a9c93b62bdbee486a9",
+    "treeHash": "e705d29be228c02db6a343bd760f5e9b83105ce8185c567541ce1e85ef78374c",
+    "generatedAt": "2025-11-28T10:14:14.681159Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "reclaim",
+    "description": "CRUD operations for Reclaim.ai tasks including create, update, list, complete, and delete with confirmation workflow"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "fb49bb27eefc4f0623e286ddc2e4a64cfaddef54c287cb8c63433113171d4606"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "95682965d41ef7adb352de53f3b16c15c028873fd2bb209c2c02910be6a84236"
+      },
+      {
+        "path": "skills/reclaim-tasks/EXAMPLES.md",
+        "sha256": "b5239fba3ce1423b5b64e87c50e12cf2d50b703c72b099160114ba3d0b5b339d"
+      },
+      {
+        "path": "skills/reclaim-tasks/REFERENCE.md",
+        "sha256": "5d48a957d742200437480732fa219c690f131b0180278bcef14cfdb9c4bcbde1"
+      },
+      {
+        "path": "skills/reclaim-tasks/SKILL.md",
+        "sha256": "a7fbcff300ea2e0f2e0af2fc3ee606c02fbbcfdfc68bda26ea911be3e8225ca8"
+      }
+    ],
+    "dirSha256": "e705d29be228c02db6a343bd760f5e9b83105ce8185c567541ce1e85ef78374c"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}

skills/reclaim-tasks/EXAMPLES.md

@@ -0,0 +1,390 @@
+# Reclaim Tasks: Examples
+
+Comprehensive examples for all Reclaim task workflows. Remember: All write operations (create, update, complete, delete) require confirmation using AskUserQuestion before execution.
+
+## Quick Task Capture
+
+### Minimal task creation
+```bash
+reclaim create --title "Review documents"
+```
+
+### Task with duration only
+```bash
+reclaim create --title "Research competitors" --duration 2
+```
+
+### Task with due date
+```bash
+reclaim create --title "Submit report" --due 2025-11-15
+```
+
+### Task with priority
+```bash
+reclaim create --title "Fix critical bug" --priority P1
+```
+
+## Detailed Task Creation
+
+### Complete task specification
+```bash
+reclaim create \
+  --title "Write quarterly review" \
+  --due 2025-11-30 \
+  --priority P2 \
+  --duration 4 \
+  --time-scheme work \
+  --notes "Include metrics from Q3 and Q4"
+```
+
+### Task with specific start time
+```bash
+reclaim create \
+  --title "Client presentation" \
+  --start 2025-11-10T14:00:00 \
+  --duration 1.5 \
+  --priority P1
+```
+
+### Deferred task (start after specific date)
+```bash
+reclaim create \
+  --title "Plan 2026 roadmap" \
+  --defer 2025-12-01 \
+  --duration 3 \
+  --priority P2
+```
+
+### Task with splitting enabled
+```bash
+# Allow splitting with default minimum chunk
+reclaim create \
+  --title "Code review backlog" \
+  --duration 4 \
+  --split
+
+# Allow splitting with 30-minute minimum chunks
+reclaim create \
+  --title "Email cleanup" \
+  --duration 3 \
+  --split 0.5
+
+# Splitting with min and max chunk constraints
+reclaim create \
+  --title "Documentation updates" \
+  --duration 6 \
+  --split \
+  --min-chunk 0.5 \
+  --max-chunk 2
+```
+
+## Task Updates
+
+### Update task title
+```bash
+reclaim update abc123 --title "Updated title"
+```
+
+### Change priority
+```bash
+reclaim update abc123 --priority P1
+```
+
+### Update due date
+```bash
+reclaim update abc123 --due 2025-11-20
+```
+
+### Update duration
+```bash
+reclaim update abc123 --duration 2.5
+```
+
+### Multiple updates at once
+```bash
+reclaim update abc123 \
+  --title "Refactored title" \
+  --priority P2 \
+  --duration 3 \
+  --due 2025-11-25
+```
+
+### Clear a date field
+```bash
+# Clear due date
+reclaim update abc123 --due none
+
+# Clear deferred start
+reclaim update abc123 --defer clear
+
+# Clear specific start time
+reclaim update abc123 --start null
+```
+
+### Add or update notes
+```bash
+reclaim update abc123 --notes "Updated context and requirements"
+```
+
+### Change time scheme
+```bash
+# Using alias
+reclaim update abc123 --time-scheme work
+
+# Using specific scheme ID
+reclaim update abc123 --time-scheme ts_abc123def
+```
+
+## Listing and Filtering
+
+### List active tasks (default)
+```bash
+reclaim
+# or explicitly
+reclaim list active
+```
+
+### List completed tasks
+```bash
+reclaim list completed
+```
+
+### List overdue tasks
+```bash
+reclaim list overdue
+```
+
+### Get specific task details
+```bash
+reclaim get abc123
+```
+
+### List available time schemes
+```bash
+reclaim list-schemes
+```
+
+## Task Completion
+
+### Mark task as complete (ARCHIVED status)
+```bash
+reclaim complete abc123
+```
+
+Note: This sets the task to ARCHIVED status, which represents truly complete tasks in Reclaim.
+
+## Task Deletion
+
+### Permanently delete a task
+```bash
+reclaim delete abc123
+```
+
+Warning: This is permanent deletion. Use `complete` instead if you want to mark a task as done.
+
+## Duration Formats
+
+Tasks can have various durations specified in hours:
+
+```bash
+# 15 minutes
+reclaim create --title "Quick check-in" --duration 0.25
+
+# 30 minutes
+reclaim create --title "Review PR" --duration 0.5
+
+# 45 minutes
+reclaim create --title "Team standup" --duration 0.75
+
+# 1 hour
+reclaim create --title "Deep work session" --duration 1
+
+# 90 minutes
+reclaim create --title "Workshop prep" --duration 1.5
+
+# 2 hours
+reclaim create --title "Client meeting" --duration 2
+
+# 4 hours (half day)
+reclaim create --title "Strategic planning" --duration 4
+
+# 8 hours (full day)
+reclaim create --title "Conference attendance" --duration 8
+```
+
+## Date and Time Formats
+
+### Date only (YYYY-MM-DD)
+```bash
+reclaim create --title "Submit proposal" --due 2025-11-30
+```
+
+### Date with time (YYYY-MM-DDTHH:MM:SS)
+```bash
+reclaim create --title "Presentation" --start 2025-11-15T14:30:00
+```
+
+### Clearing dates
+```bash
+# All of these work to clear a date field
+reclaim update abc123 --due none
+reclaim update abc123 --defer clear
+reclaim update abc123 --start null
+```
+
+## Workflow Examples
+
+### Morning planning workflow
+```bash
+# List what's scheduled
+reclaim list active
+
+# Check overdue items
+reclaim list overdue
+
+# Adjust priorities based on day
+reclaim update task1 --priority P1
+reclaim update task2 --defer 2025-11-08
+```
+
+### Creating a project task series
+```bash
+# Phase 1: Research (this week)
+reclaim create \
+  --title "Research: User interviews" \
+  --due 2025-11-08 \
+  --priority P1 \
+  --duration 3 \
+  --split 1
+
+# Phase 2: Design (next week)
+reclaim create \
+  --title "Design: Wireframes" \
+  --defer 2025-11-11 \
+  --duration 4 \
+  --priority P2
+
+# Phase 3: Implementation (following week)
+reclaim create \
+  --title "Implementation: Core features" \
+  --defer 2025-11-18 \
+  --duration 8 \
+  --priority P2 \
+  --split 2
+```
+
+### End of day cleanup
+```bash
+# Complete finished tasks
+reclaim complete task1
+reclaim complete task2
+
+# Defer tasks that weren't started
+reclaim update task3 --defer 2025-11-08
+
+# Review what's coming up
+reclaim list active
+```
+
+## Time Scheme Examples
+
+### Using work hours
+```bash
+reclaim create \
+  --title "Code review" \
+  --duration 2 \
+  --time-scheme work
+```
+
+### Using personal time
+```bash
+reclaim create \
+  --title "Side project work" \
+  --duration 1.5 \
+  --time-scheme personal
+```
+
+### Finding and using specific schemes
+```bash
+# List all available schemes
+reclaim list-schemes
+
+# Use specific scheme ID
+reclaim create \
+  --title "Deep focus work" \
+  --duration 3 \
+  --time-scheme ts_abc123def
+```
+
+## Private Tasks
+
+### Create a private task
+```bash
+reclaim create \
+  --title "Personal development review" \
+  --duration 1 \
+  --private true
+```
+
+### Make existing task private
+```bash
+reclaim update abc123 --private true
+```
+
+### Make task non-private
+```bash
+reclaim update abc123 --private false
+```
+
+## Category and Color
+
+### Set event category
+```bash
+reclaim create \
+  --title "Team meeting" \
+  --duration 1 \
+  --category "Meetings"
+```
+
+### Set event color
+```bash
+reclaim create \
+  --title "Deep work block" \
+  --duration 2 \
+  --color "blue"
+```
+
+### Update category and color
+```bash
+reclaim update abc123 --category "Planning" --color "green"
+```
+
+## Confirmation Workflow Example
+
+When a user asks: "Create a task to finish the proposal, P1, due next Friday, 3 hours"
+
+**Step 1**: Construct the command
+```bash
+reclaim create \
+  --title "Finish the proposal" \
+  --priority P1 \
+  --due 2025-11-14 \
+  --duration 3
+```
+
+**Step 2**: Use AskUserQuestion with:
+```
+Ready to create this Reclaim task:
+
+Command: reclaim create --title "Finish the proposal" --priority P1 --due 2025-11-14 --duration 3
+
+This will create:
+- Title: "Finish the proposal"
+- Priority: P1
+- Due: 2025-11-14
+- Duration: 3 hours
+
+Proceed?
+```
+
+**Step 3**: After user confirms, execute the command

skills/reclaim-tasks/REFERENCE.md

@@ -0,0 +1,520 @@
+# Reclaim Tasks: Complete Reference
+
+Complete reference documentation for the `reclaim` CLI.
+
+## Commands
+
+### list [FILTER]
+List tasks with optional filter.
+
+**Filters:**
+- `active` (default when no command given) - Lists scheduled and in-progress tasks
+- `completed` - Lists completed tasks
+- `overdue` - Lists tasks past their due date
+
+**Examples:**
+```bash
+reclaim                # List active tasks (default)
+reclaim list           # List active tasks (explicit)
+reclaim list active    # List active tasks
+reclaim list completed # List completed tasks
+reclaim list overdue   # List overdue tasks
+```
+
+### create
+Create a new task. Requires `--title` at minimum.
+
+**Required:**
+- `--title TITLE` - Task title
+
+**Optional:** See "Task Options" section below
+
+**Examples:**
+```bash
+reclaim create --title "My task"
+reclaim create --title "Important work" --due 2025-11-15 --priority P1
+```
+
+### get TASK_ID
+Get detailed information about a specific task.
+
+**Arguments:**
+- `TASK_ID` - The unique identifier for the task
+
+**Examples:**
+```bash
+reclaim get abc123
+```
+
+### update TASK_ID
+Update an existing task. At least one option must be provided.
+
+**Arguments:**
+- `TASK_ID` - The unique identifier for the task
+
+**Options:** See "Task Options" section below
+
+**Examples:**
+```bash
+reclaim update abc123 --title "Updated title"
+reclaim update abc123 --priority P1 --due 2025-11-20
+```
+
+### complete TASK_ID
+Mark a task as complete (sets status to ARCHIVED).
+
+**Arguments:**
+- `TASK_ID` - The unique identifier for the task
+
+**Examples:**
+```bash
+reclaim complete abc123
+```
+
+**Note:** This sets the task to ARCHIVED status, which represents a truly completed task in Reclaim.
+
+### delete TASK_ID
+Permanently delete a task. This action cannot be undone.
+
+**Arguments:**
+- `TASK_ID` - The unique identifier for the task
+
+**Examples:**
+```bash
+reclaim delete abc123
+```
+
+**Warning:** This is permanent deletion. Use `complete` if you want to mark a task as done while preserving it.
+
+### list-schemes
+List all available time schemes for the account.
+
+**Examples:**
+```bash
+reclaim list-schemes
+```
+
+### help
+Show help message with command and option reference.
+
+**Examples:**
+```bash
+reclaim help
+reclaim --help
+```
+
+## Task Options
+
+Options available for `create` and `update` commands.
+
+### --title TITLE
+Task title text.
+
+**Type:** String
+**Required for:** create
+**Optional for:** update
+
+**Examples:**
+```bash
+--title "Write quarterly report"
+--title "Review PR #123"
+```
+
+### --due DATE
+Task due date. Can be a date or date-time.
+
+**Type:** Date (YYYY-MM-DD) or DateTime (YYYY-MM-DDTHH:MM:SS)
+**Special values:** `none`, `clear`, `null` (to remove due date)
+
+**Examples:**
+```bash
+--due 2025-11-30
+--due 2025-11-30T17:00:00
+--due none  # Clear the due date
+```
+
+### --priority PRIORITY
+Task priority level.
+
+**Type:** P1, P2, P3, or P4
+**Default:** P3 (when not specified)
+
+**Priority levels:**
+- `P1` - Highest priority (most urgent/important)
+- `P2` - High priority
+- `P3` - Medium priority (default)
+- `P4` - Low priority
+
+**Examples:**
+```bash
+--priority P1
+--priority P4
+```
+
+### --duration HOURS
+Task duration in hours.
+
+**Type:** Decimal number
+**Common values:**
+- `0.25` - 15 minutes
+- `0.5` - 30 minutes
+- `0.75` - 45 minutes
+- `1` - 1 hour
+- `1.5` - 90 minutes
+- `2` - 2 hours
+- `4` - 4 hours (half day)
+- `8` - 8 hours (full day)
+
+**Examples:**
+```bash
+--duration 2
+--duration 0.5
+--duration 1.5
+```
+
+### --split [CHUNK_SIZE]
+Allow Reclaim to split the task into smaller chunks across multiple time slots.
+
+**Type:** Optional decimal number (minimum chunk size in hours)
+**Default:** When flag is present without value, Reclaim uses its default minimum
+
+**Examples:**
+```bash
+--split              # Allow splitting with default minimum
+--split 0.5          # Allow splitting, minimum 30-minute chunks
+--split 1            # Allow splitting, minimum 1-hour chunks
+```
+
+**Note:** Use with `--min-chunk` and `--max-chunk` for finer control.
+
+### --min-chunk HOURS
+Minimum chunk size when task splitting is enabled.
+
+**Type:** Decimal number (hours)
+**Requires:** `--split` flag
+
+**Examples:**
+```bash
+--split --min-chunk 0.5   # Minimum 30-minute chunks
+--split --min-chunk 1     # Minimum 1-hour chunks
+```
+
+### --max-chunk HOURS
+Maximum chunk size when task splitting is enabled.
+
+**Type:** Decimal number (hours)
+**Requires:** `--split` flag
+
+**Examples:**
+```bash
+--split --max-chunk 2     # Maximum 2-hour chunks
+--split --min-chunk 0.5 --max-chunk 2  # Between 30min and 2 hours
+```
+
+### --min-work HOURS
+Minimum total work duration.
+
+**Type:** Decimal number (hours)
+
+**Examples:**
+```bash
+--min-work 1
+--min-work 0.5
+```
+
+### --max-work HOURS
+Maximum total work duration.
+
+**Type:** Decimal number (hours)
+
+**Examples:**
+```bash
+--max-work 4
+--max-work 2
+```
+
+### --defer DATE
+Start task after this date/time. Task won't be scheduled before this date.
+
+**Type:** Date (YYYY-MM-DD) or DateTime (YYYY-MM-DDTHH:MM:SS)
+**Special values:** `none`, `clear`, `null` (to remove defer date)
+**Alias:** `--snooze` (same functionality)
+
+**Examples:**
+```bash
+--defer 2025-11-15
+--defer 2025-11-15T09:00:00
+--defer none  # Clear the defer date
+```
+
+### --snooze DATE
+Synonym for `--defer`. Start task after this date/time.
+
+**Type:** Date (YYYY-MM-DD) or DateTime (YYYY-MM-DDTHH:MM:SS)
+**Special values:** `none`, `clear`, `null` (to remove snooze date)
+
+**Examples:**
+```bash
+--snooze 2025-11-20
+--snooze none  # Clear the snooze date
+```
+
+### --start DATE
+Specific start time for the task. Locks the task to a specific calendar slot.
+
+**Type:** DateTime (YYYY-MM-DDTHH:MM:SS)
+**Special values:** `none`, `clear`, `null` (to remove specific start time)
+
+**Examples:**
+```bash
+--start 2025-11-15T14:00:00
+--start none  # Clear the specific start time
+```
+
+**Note:** This pins the task to a specific calendar time rather than letting Reclaim schedule it flexibly.
+
+### --time-scheme SCHEME
+Time scheme that defines when the task can be scheduled.
+
+**Type:** Time scheme ID or alias
+
+**Common aliases:**
+- `work`, `working hours`, `business hours` - Finds schemes containing 'work'
+- `personal`, `off hours`, `private` - Finds schemes containing 'personal'
+
+**Examples:**
+```bash
+--time-scheme work
+--time-scheme personal
+--time-scheme ts_abc123def  # Specific scheme ID
+```
+
+**Note:** Use `reclaim list-schemes` to see available time schemes.
+
+### --private BOOL
+Make the task private (hidden from others who can see your calendar).
+
+**Type:** Boolean (true or false)
+
+**Examples:**
+```bash
+--private true
+--private false
+```
+
+### --category CATEGORY
+Event category for grouping and filtering.
+
+**Type:** String
+
+**Examples:**
+```bash
+--category "Meetings"
+--category "Deep Work"
+--category "Planning"
+```
+
+### --color COLOR
+Color for the event on your calendar.
+
+**Type:** Color name or code
+
+**Examples:**
+```bash
+--color blue
+--color red
+--color green
+```
+
+### --notes TEXT
+Additional notes or description for the task.
+
+**Type:** String (may require quotes if contains spaces)
+
+**Examples:**
+```bash
+--notes "Need to include Q3 metrics"
+--notes "Follow up with John about API changes"
+```
+
+## Date and Time Formats
+
+### Date Format
+**Format:** `YYYY-MM-DD`
+**Examples:**
+- `2025-11-15`
+- `2025-12-31`
+- `2026-01-01`
+
+### DateTime Format
+**Format:** `YYYY-MM-DDTHH:MM:SS`
+**Examples:**
+- `2025-11-15T14:30:00` (2:30 PM)
+- `2025-11-15T09:00:00` (9:00 AM)
+- `2025-11-20T16:45:00` (4:45 PM)
+
+### Clearing Dates
+To remove a date field, use any of these special values:
+- `none`
+- `clear`
+- `null`
+
+**Examples:**
+```bash
+reclaim update abc123 --due none
+reclaim update abc123 --defer clear
+reclaim update abc123 --start null
+```
+
+## Status Values
+
+Tasks in Reclaim can have the following statuses:
+
+- `SCHEDULED` - Task is scheduled on the calendar
+- `IN_PROGRESS` - Task is currently being worked on
+- `COMPLETE` - Task is marked complete but still active
+- `ARCHIVED` - Task is truly completed (set by `reclaim complete`)
+
+**Note:** The `complete` command sets status to `ARCHIVED`, which represents a truly finished task.
+
+## Time Scheme Aliases
+
+When using `--time-scheme`, you can use aliases instead of scheme IDs:
+
+### Work-related aliases:
+- `work`
+- `working hours`
+- `business hours`
+
+These find schemes containing "work" in their name.
+
+### Personal-related aliases:
+- `personal`
+- `off hours`
+- `private`
+
+These find schemes containing "personal" in their name.
+
+**Example:**
+```bash
+reclaim create --title "Code review" --duration 2 --time-scheme work
+```
+
+## GTD Integration
+
+The CLI supports GTD (Getting Things Done) integration:
+
+### ID Tracking Format
+Store Reclaim task IDs in your GTD system (e.g., NEXT.md) using this format:
+
+```
+[Reclaim:task_id]
+```
+
+**Example:**
+```markdown
+- [ ] Finish quarterly report [Reclaim:abc123def]
+- [ ] Review team PRs [Reclaim:xyz789ghi]
+```
+
+This allows you to sync your GTD system with Reclaim tasks.
+
+## Error Handling
+
+### Common errors:
+
+**Missing required fields:**
+```
+Error: --title is required for create command
+```
+Solution: Provide the `--title` option.
+
+**Invalid task ID:**
+```
+Error: Task not found: abc123
+```
+Solution: Verify the task ID using `reclaim list` or `reclaim list completed`.
+
+**Invalid date format:**
+```
+Error: Invalid date format
+```
+Solution: Use `YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS` format.
+
+**Invalid priority:**
+```
+Error: Priority must be P1, P2, P3, or P4
+```
+Solution: Use one of the four priority levels.
+
+## Best Practices
+
+### Use priorities wisely
+- Reserve `P1` for truly urgent and important tasks
+- Use `P2` for important but less urgent work
+- Default `P3` works for most regular tasks
+- Use `P4` for nice-to-have items
+
+### Set realistic durations
+- Be honest about how long tasks take
+- Include buffer time for context switching
+- Consider using `--split` for longer tasks to allow flexible scheduling
+
+### Use time schemes effectively
+- Create separate schemes for work and personal time
+- Use schemes to enforce work-life boundaries
+- Apply the right scheme to ensure tasks are scheduled appropriately
+
+### Defer vs Start
+- Use `--defer` when you want Reclaim to schedule the task flexibly after a date
+- Use `--start` when the task MUST happen at a specific time
+- Avoid over-using `--start` as it reduces scheduling flexibility
+
+### Task splitting strategy
+- Enable `--split` for tasks longer than 2 hours
+- Set `--min-chunk` to maintain focus (e.g., 1 hour minimum)
+- Set `--max-chunk` to prevent overly long blocks
+
+### Keep tasks actionable
+- Use clear, action-oriented titles
+- Add context in `--notes` for future reference
+- Complete or delete tasks promptly to keep your list current
+
+## Complete Examples
+
+### Complex task creation
+```bash
+reclaim create \
+  --title "Q4 Planning Session" \
+  --due 2025-11-30 \
+  --priority P2 \
+  --duration 6 \
+  --split \
+  --min-chunk 1.5 \
+  --max-chunk 3 \
+  --time-scheme work \
+  --category "Planning" \
+  --color blue \
+  --notes "Include team input from retrospective"
+```
+
+### Full task update
+```bash
+reclaim update abc123 \
+  --title "Updated: Q4 Planning Session" \
+  --priority P1 \
+  --due 2025-11-25 \
+  --duration 4 \
+  --notes "Deadline moved up due to executive meeting"
+```
+
+### Task with deferred start and specific duration
+```bash
+reclaim create \
+  --title "Annual review preparation" \
+  --defer 2025-12-01 \
+  --duration 3 \
+  --priority P2 \
+  --time-scheme personal \
+  --private true
+```

skills/reclaim-tasks/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: reclaim-tasks
+description: Manage tasks in Reclaim.ai calendar scheduling app. Use when creating, updating, listing, completing, or deleting Reclaim tasks, or working with calendar scheduling, task priorities, time blocking, or task duration management.
+---
+
+# Reclaim Tasks
+
+Manage CRUD operations for tasks in Reclaim.ai using the `reclaim` CLI.
+
+## Installation Check
+
+**IMPORTANT**: Before using any Reclaim commands, always check if the `reclaim` CLI is installed:
+
+```bash
+which reclaim
+```
+
+If not installed, install it automatically based on the system:
+
+**All systems** (requires Ruby):
+```bash
+gem install reclaim
+```
+
+If automatic installation fails, inform the user that they need to install Ruby first, then run `gem install reclaim`.
+
+After installation, verify it works:
+```bash
+reclaim --help
+```
+
+## Mandatory Confirmation Workflow
+
+**CRITICAL**: For ALL write operations (create, update, complete, delete), you MUST:
+
+1. Parse the user's request and construct the `reclaim` command
+2. Use the AskUserQuestion tool to show the command and get confirmation
+3. Only execute the command after user approval
+
+**Read operations** (list, get, list-schemes) can execute immediately without confirmation.
+
+## Quick Command Reference
+
+### Read Operations (no confirmation needed)
+```bash
+reclaim                    # List active tasks (default)
+reclaim list active        # List active tasks (explicit)
+reclaim list completed     # List completed tasks
+reclaim list overdue       # List overdue tasks
+reclaim get TASK_ID        # Get task details
+reclaim list-schemes       # List available time schemes
+```
+
+### Write Operations (REQUIRE confirmation)
+```bash
+# Create
+reclaim create --title "TITLE" [OPTIONS]
+
+# Update
+reclaim update TASK_ID [OPTIONS]
+
+# Complete
+reclaim complete TASK_ID
+
+# Delete
+reclaim delete TASK_ID
+```
+
+## Common Options
+
+- `--title TITLE` - Task title
+- `--due DATE` - Due date (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SS, or "none" to clear)
+- `--priority P1|P2|P3|P4` - Task priority
+- `--duration HOURS` - Duration in hours (0.25 = 15min, 1.5 = 90min)
+- `--split [CHUNK_SIZE]` - Allow task splitting (optional min chunk size)
+- `--defer DATE` - Start after this date (or "none" to clear)
+- `--start DATE` - Specific start time (or "none" to clear)
+- `--time-scheme SCHEME` - Time scheme ID or alias (work, personal, etc.)
+- `--notes TEXT` - Task notes/description
+
+## Example Workflow with Confirmation
+
+**User request**: "Create a task called 'Write proposal' due Friday, P1 priority, 3 hours"
+
+**Your response**:
+1. Construct command: `reclaim create --title "Write proposal" --due 2025-11-07 --priority P1 --duration 3`
+2. Use AskUserQuestion to confirm:
+   ```
+   Ready to create this Reclaim task:
+
+   Command: reclaim create --title "Write proposal" --due 2025-11-07 --priority P1 --duration 3
+
+   This will create a P1 task with 3 hours duration due on 2025-11-07.
+
+   Proceed?
+   ```
+3. After approval, execute the command
+
+## Additional Resources
+
+- [EXAMPLES.md](EXAMPLES.md) - Comprehensive examples for all workflows
+- [REFERENCE.md](REFERENCE.md) - Complete option and command reference
+
+## Date Formats
+
+- Standard: `YYYY-MM-DD` (e.g., 2025-11-07)
+- With time: `YYYY-MM-DDTHH:MM:SS` (e.g., 2025-11-07T14:30:00)
+- Clear date: `none`, `clear`, or `null`
+
+## Priority Levels
+
+- `P1` - Highest priority
+- `P2` - High priority
+- `P3` - Medium priority
+- `P4` - Low priority
+
+## Time Scheme Aliases
+
+- `work`, `working hours`, `business hours` → Work time schemes
+- `personal`, `off hours`, `private` → Personal time schemes
+
+## Understanding Task Status
+
+**CRITICAL**: The `reclaim list active` output shows status COMPLETE with checkmarks (✓) for tasks that are
+**done scheduling** (past their assigned time blocks), NOT tasks that are marked as "done".
+
+- Status: COMPLETE in API (✓ symbol) = Task's scheduled time is in the past
+- Status: SCHEDULED (○ symbol) = Task's scheduled time is in the future
+
+**A task is only truly "done" after you run `reclaim complete TASK_ID`**. Until then, all tasks in
+the active list are open work items, regardless of checkmarks or "COMPLETE" status in the API
+response.