@scardis/omnifocus-mcp 0.1.0

package/openspec/specs/forecast/spec.md

@@ -0,0 +1,15 @@
+# forecast
+
+## Purpose
+
+Covers OmniFocus Forecast data, including forecast days, tasks due or deferred on a given day, the configured forecast tag, and forecast badge counts. Individual tools will be defined in the `forecast-and-inspection` change.
+
+## Requirements
+
+### Requirement: Capability declared
+
+The `forecast` capability SHALL cover OmniFocus Forecast data, including forecast days, tasks due or deferred on a given day, the configured forecast tag, and forecast badge counts. Requirements for individual tools SHALL be added by the `forecast-and-inspection` change.
+
+#### Scenario: Capability is named and scoped
+- **WHEN** a future change proposes adding forecast tools
+- **THEN** it lands requirements under this capability rather than inventing a new capability name

package/openspec/specs/identity-resolution/spec.md

@@ -0,0 +1,51 @@
+# identity-resolution
+
+## Purpose
+
+Defines how OmniFocus entities are addressed and resolved — canonical ID addressing, name/path-based lookup with ambiguity reporting, and the folder path format.
+
+## Requirements
+
+### Requirement: Canonical ID addressing
+
+The system SHALL use `id.primaryKey` as the canonical identifier for every addressable OmniFocus entity (Task, Project, Folder, Tag, Perspective). Every read tool SHALL return an `id` field carrying this value. Every write tool (in this and future changes) SHALL accept an `id` parameter as its primary addressing mode.
+
+#### Scenario: Read tools return primary key
+- **WHEN** a caller invokes `list_projects`
+- **THEN** every returned element has an `id` field equal to the OmniJS expression `project.id.primaryKey` for that project
+
+#### Scenario: IDs are stable within a session
+- **WHEN** a caller reads a project's ID via `list_projects`, then reads the same project again via `get_project` using that ID
+- **THEN** the second read succeeds and returns the same project, without re-resolving by name
+
+### Requirement: Name and path resolution with ambiguity reporting
+
+The system SHALL provide a `resolve_name` tool that accepts `{type, query, scope?}` and returns a list of candidate entities `[{id, name, path, type, ...}]`. When more than one entity matches the query, the tool SHALL return all matches and SHALL NOT silently pick a winner. The caller is responsible for disambiguating.
+
+#### Scenario: Unique match returns single candidate
+- **WHEN** `resolve_name` is called with `{type: "project", query: "Q4 Planning"}` and exactly one project has that name
+- **THEN** the tool returns a list with one element containing the project's id, name, and full folder path
+
+#### Scenario: Ambiguous match returns all candidates
+- **WHEN** `resolve_name` is called with `{type: "project", query: "Inbox Cleanup"}` and two projects have that name under different folders
+- **THEN** the tool returns a list with both candidates, each carrying a distinct id and distinct folder path
+
+#### Scenario: No match returns empty list
+- **WHEN** `resolve_name` is called with a query that matches no entity of the requested type
+- **THEN** the tool returns an empty list and does not throw an error
+
+#### Scenario: Path-qualified query narrows scope
+- **WHEN** `resolve_name` is called with `{type: "folder", query: "Acme", scope: "Work ▸ Clients"}`
+- **THEN** the tool returns only folders named "Acme" that are direct or transitive children of the folder at path "Work ▸ Clients"
+
+### Requirement: Folder path addressing
+
+The system SHALL represent folder paths as strings using the separator ` ▸ ` (U+25B8 with surrounding spaces) and SHALL support resolving a folder by its full path as an alternative to its ID. When a path is ambiguous (the same path exists under multiple roots, which cannot occur for folders but can for tags), the resolution SHALL report the ambiguity through `resolve_name`.
+
+#### Scenario: Folder resolves by full path
+- **WHEN** `resolve_name` is called with `{type: "folder", query: "Work ▸ Clients ▸ Acme"}`
+- **THEN** the tool returns the folder whose full ancestor chain matches that path exactly
+
+#### Scenario: Returned paths use the canonical separator
+- **WHEN** any read tool returns a folder path or a project's containing folder path
+- **THEN** the path uses ` ▸ ` as the separator between ancestor names

package/openspec/specs/move-operations/spec.md

@@ -0,0 +1,41 @@
+## Requirements
+
+### Requirement: Move task to a new container
+
+The system SHALL provide a `move_task` tool that accepts `{id: string, projectId?: string, parentTaskId?: string}` and moves the specified task to the given container. Exactly one of `projectId` or `parentTaskId` SHALL be provided; if both or neither are given, the tool SHALL return a validation error. When `projectId` is provided, the task SHALL become a top-level task in that project. When `parentTaskId` is provided, the task SHALL become a direct subtask of that task. The tool SHALL return a structured not-found error if any of the IDs do not correspond to existing objects.
+
+#### Scenario: Move task to a project
+- **WHEN** `move_task` is called with `{id: "t1", projectId: "p2"}`
+- **THEN** the task appears as a top-level task in project p2 and is no longer in its previous container
+
+#### Scenario: Make task a subtask
+- **WHEN** `move_task` is called with `{id: "t1", parentTaskId: "t2"}`
+- **THEN** the task becomes a direct child of task t2
+
+#### Scenario: Both destinations provided is a validation error
+- **WHEN** `move_task` is called with both `projectId` and `parentTaskId`
+- **THEN** the tool returns a validation error before any snippet executes
+
+#### Scenario: Non-existent task ID returns not-found error
+- **WHEN** `move_task` is called with an ID that does not correspond to any task
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Move project to a folder
+
+The system SHALL provide a `move_project` tool that accepts `{id: string, folderId: string | null}` and moves the specified project to the given folder. When `folderId` is `null`, the project SHALL be moved to the top level (no containing folder). The tool SHALL return a structured not-found error if the project ID or folder ID does not correspond to an existing object.
+
+#### Scenario: Move project to a folder
+- **WHEN** `move_project` is called with `{id: "p1", folderId: "f2"}`
+- **THEN** the project is now contained within folder f2
+
+#### Scenario: Move project to top level
+- **WHEN** `move_project` is called with `{id: "p1", folderId: null}`
+- **THEN** the project has no parent folder
+
+#### Scenario: Non-existent project ID returns not-found error
+- **WHEN** `move_project` is called with a project ID that does not exist
+- **THEN** the tool returns a structured not-found error
+
+#### Scenario: Non-existent folder ID returns not-found error
+- **WHEN** `move_project` is called with a folderId that does not correspond to any folder
+- **THEN** the tool returns a structured not-found error

package/openspec/specs/perspective-management/spec.md

@@ -0,0 +1,15 @@
+# perspective-management
+
+## Purpose
+
+Covers listing built-in and custom perspectives, reading perspective metadata, and activating a perspective in a document window. Individual tools will be defined in the `perspectives-and-windows` change.
+
+## Requirements
+
+### Requirement: Capability declared
+
+The `perspective-management` capability SHALL cover listing built-in and custom perspectives, reading perspective metadata, and activating a perspective in a document window. Custom perspective *creation and editing* are a non-goal pending verification of OmniJS scriptability of `Perspective.Custom` definitions; if a future investigation proves the API is available, the non-goal may be revisited by a later change. Requirements for individual tools SHALL be added by the `perspectives-and-windows` change.
+
+#### Scenario: Capability is named and scoped
+- **WHEN** a future change proposes adding perspective tools
+- **THEN** it lands requirements under this capability rather than inventing a new capability name

package/openspec/specs/project-filtering/spec.md

@@ -0,0 +1,72 @@
+# project-filtering
+
+## Purpose
+
+Defines filtering and limiting behavior for the `list_projects` tool, including status, folder, and flagged filters, as well as result limits and enriched project summary fields.
+
+## Requirements
+
+### Requirement: Filter list_projects results
+
+The system SHALL allow `list_projects` to accept an optional `filter` object that restricts which projects are returned. All filter fields are optional and combine as AND conditions. When `filter.status` is omitted, the tool SHALL exclude projects with status `done` or `dropped` by default.
+
+Filter fields:
+- `status` (array of ProjectStatus): return only projects whose status is in the array; overrides the default exclusion of done/dropped
+- `folderId` (string): return only projects within the specified folder or any of its descendant folders; throws not-found if the folder ID does not exist
+- `flagged` (boolean): when `true`, return only flagged projects
+
+#### Scenario: Default excludes done and dropped projects
+- **WHEN** `list_projects` is called with no filter
+- **THEN** the tool returns only projects with status `active` or `onHold`
+
+#### Scenario: Filter by status array
+- **WHEN** `list_projects` is called with `{ filter: { status: ["active"] } }`
+- **THEN** the tool returns only active projects
+
+#### Scenario: Explicit status filter retrieves done projects
+- **WHEN** `list_projects` is called with `{ filter: { status: ["done"] } }`
+- **THEN** the tool returns completed projects (the default exclusion does not apply)
+
+#### Scenario: Filter by folderId returns projects in subtree
+- **WHEN** `list_projects` is called with `{ filter: { folderId: "abc123" } }`
+- **THEN** the tool returns only projects whose parent folder chain includes the specified folder
+
+#### Scenario: Non-existent folderId returns not-found error
+- **WHEN** `list_projects` is called with a `folderId` that does not correspond to any folder
+- **THEN** the tool returns a structured not-found error
+
+#### Scenario: Filter by flagged
+- **WHEN** `list_projects` is called with `{ filter: { flagged: true } }`
+- **THEN** the tool returns only flagged projects, excluding done and dropped projects
+
+#### Scenario: Combined filters act as AND
+- **WHEN** `list_projects` is called with `{ filter: { status: ["active"], flagged: true } }`
+- **THEN** the tool returns only projects that are both active AND flagged
+
+### Requirement: Limit list_projects results
+
+The system SHALL allow `list_projects` to accept an optional `limit` integer that caps the number of projects returned. When `limit` is omitted, a default of 100 SHALL apply.
+
+#### Scenario: Default limit of 100
+- **WHEN** `list_projects` is called without a `limit` and more than 100 projects match
+- **THEN** the tool returns at most 100 projects
+
+#### Scenario: Custom limit
+- **WHEN** `list_projects` is called with `{ limit: 20 }`
+- **THEN** the tool returns at most 20 projects
+
+### Requirement: Enriched project summary includes flagged and folderId
+
+The `ProjectSummary` returned by `list_projects` SHALL include `flagged` (boolean) and `folderId` (string or null) in addition to existing fields. `folderId` SHALL be the direct parent folder's `id.primaryKey`, or `null` for top-level projects.
+
+#### Scenario: Summary includes flagged
+- **WHEN** `list_projects` returns a flagged project
+- **THEN** the project summary includes `flagged: true`
+
+#### Scenario: Summary includes folderId for nested project
+- **WHEN** `list_projects` returns a project inside a folder
+- **THEN** the project summary includes `folderId` set to the parent folder's ID
+
+#### Scenario: Summary includes folderId null for top-level project
+- **WHEN** `list_projects` returns a top-level project with no containing folder
+- **THEN** the project summary includes `folderId: null`

package/openspec/specs/project-management/spec.md

@@ -0,0 +1,31 @@
+# project-management
+
+## Purpose
+
+Defines tools for reading and listing OmniFocus projects, including full project listing and detail retrieval by ID.
+
+## Requirements
+
+### Requirement: List projects
+
+The system SHALL provide a `list_projects` tool that returns projects in the OmniFocus database as an array of summaries, each containing `{id, name, folderPath, folderId, status, type, flagged}`. The `status` field SHALL be one of `"active" | "onHold" | "done" | "dropped"`. The `type` field SHALL be one of `"parallel" | "sequential" | "singleActions"`. The `folderPath` field SHALL use the canonical ` ▸ ` separator and SHALL be an empty string for top-level projects. The `folderId` field SHALL be the direct parent folder's ID or `null` for top-level projects. The tool SHALL accept an optional `filter` object (see project-filtering spec) and an optional `limit` integer (default 100). When no `filter.status` is provided, projects with status `done` or `dropped` SHALL be excluded by default.
+
+#### Scenario: Active and on-hold projects returned by default
+- **WHEN** `list_projects` is called with no arguments
+- **THEN** the tool returns only projects with status `active` or `onHold`, each with id, name, folderPath, folderId, status, type, and flagged populated
+
+#### Scenario: Single Actions list is reported with correct type
+- **WHEN** the database contains a Single Actions list project
+- **THEN** that project appears in the result with `type: "singleActions"`, never as `"parallel"` or `"sequential"`
+
+### Requirement: Get project by ID
+
+The system SHALL provide a `get_project` tool that accepts `{id: string}` and returns the full detail record of the named project, including `{id, name, note, folderPath, status, type, flagged, deferDate, dueDate, completionDate, reviewInterval, nextReviewDate, lastReviewDate, tagIds}`. If no project exists with that ID, the tool SHALL return a structured not-found error.
+
+#### Scenario: Existing project returns full detail
+- **WHEN** `get_project` is called with the ID of an existing project
+- **THEN** the tool returns the project's full detail record
+
+#### Scenario: Missing project returns not-found error
+- **WHEN** `get_project` is called with an ID that does not correspond to any project
+- **THEN** the tool returns a structured error with a not-found code

package/openspec/specs/project-write/spec.md

@@ -0,0 +1,79 @@
+# Spec: Project Write
+
+## Purpose
+
+Provides MCP tools for creating and mutating OmniFocus projects: creating new projects, editing project properties, marking projects complete or dropped, and permanently deleting projects.
+
+## Requirements
+
+### Requirement: Create project
+
+The system SHALL provide a `create_project` tool that creates a new OmniFocus project and returns its full detail record. The tool SHALL accept `{name: string, folderId?: string, note?: string, type?: "parallel" | "sequential" | "singleActions", status?: "active" | "onHold", flagged?: boolean, deferDate?: string, dueDate?: string, reviewInterval?: {steps: number, unit: "days" | "weeks" | "months" | "years"}, tagIds?: string[]}`. If `folderId` is provided the project SHALL be created inside that folder; otherwise it SHALL be created at the top level.
+
+#### Scenario: Create top-level project
+- **WHEN** `create_project` is called with `{name: "My Project"}` and no `folderId`
+- **THEN** the tool creates the project at the top level and returns its full detail record including a stable `id`
+
+#### Scenario: Create project inside a folder
+- **WHEN** `create_project` is called with `{name: "My Project", folderId: "abc123"}`
+- **THEN** the tool creates the project inside the specified folder and returns its full detail record with `folderPath` reflecting the folder
+
+#### Scenario: Create sequential project
+- **WHEN** `create_project` is called with `{name: "My Project", type: "sequential"}`
+- **THEN** the returned project detail includes `type: "sequential"`
+
+#### Scenario: Non-existent folder returns not-found error
+- **WHEN** `create_project` is called with a `folderId` that does not correspond to any folder
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Edit project
+
+The system SHALL provide an `edit_project` tool that modifies an existing project and returns its updated full detail record. The tool SHALL accept `{id: string}` plus any subset of `{name?: string, note?: string, type?: "parallel" | "sequential" | "singleActions", status?: "active" | "onHold", flagged?: boolean, deferDate?: string | null, dueDate?: string | null, reviewInterval?: {steps: number, unit: "days" | "weeks" | "months" | "years"}, tagIds?: string[]}`. Fields omitted from the call SHALL be left unchanged. When `tagIds` is provided it SHALL replace the project's entire tag set. Passing `null` for a date SHALL clear the field. When `reviewInterval` is provided, only the `steps` value is updated; the `unit` field is accepted by the schema but cannot be changed at runtime due to OmniJS API constraints in the `evaluateJavascript` context.
+
+#### Scenario: Put project on hold
+- **WHEN** `edit_project` is called with `{id: "abc123", status: "onHold"}`
+- **THEN** the project's status becomes `"onHold"` and all other fields are unchanged
+
+#### Scenario: Set review interval
+- **WHEN** `edit_project` is called with `{id: "abc123", reviewInterval: {steps: 2, unit: "weeks"}}`
+- **THEN** the project's review interval is updated and the returned detail reflects the change
+
+#### Scenario: Non-existent project returns not-found error
+- **WHEN** `edit_project` is called with an ID that does not correspond to any project
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Complete project
+
+The system SHALL provide a `complete_project` tool that marks an existing project done using OmniJS `markComplete()` and returns the project's updated full detail record.
+
+#### Scenario: Complete an existing project
+- **WHEN** `complete_project` is called with the ID of an active project
+- **THEN** the project's status becomes `"done"` and the tool returns the updated detail record
+
+#### Scenario: Non-existent project returns not-found error
+- **WHEN** `complete_project` is called with an ID that does not correspond to any project
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Drop project
+
+The system SHALL provide a `drop_project` tool that marks an existing project dropped using OmniJS `drop()` and returns the project's updated full detail record.
+
+#### Scenario: Drop an existing project
+- **WHEN** `drop_project` is called with the ID of an active project
+- **THEN** the project's status becomes `"dropped"` and the tool returns the updated detail record
+
+#### Scenario: Non-existent project returns not-found error
+- **WHEN** `drop_project` is called with an ID that does not correspond to any project
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Delete project
+
+The system SHALL provide a `delete_project` tool that permanently deletes a project and all its tasks using OmniJS `deleteObject()`. The tool description SHALL instruct the AI to confirm with the user before invoking this tool, noting that deletion is permanent and removes all tasks within the project.
+
+#### Scenario: Delete an existing project
+- **WHEN** `delete_project` is called with the ID of an existing project
+- **THEN** the project and all its tasks are permanently removed from OmniFocus and the tool returns a confirmation envelope
+
+#### Scenario: Non-existent project returns not-found error
+- **WHEN** `delete_project` is called with an ID that does not correspond to any project
+- **THEN** the tool returns a structured not-found error

package/openspec/specs/recurrence/spec.md

@@ -0,0 +1,51 @@
+# recurrence
+
+## Purpose
+
+Covers the construction, assignment, reading, and clearing of `Task.RepetitionRule` values on OmniFocus tasks.
+
+## Requirements
+
+### Requirement: Capability declared
+
+The `recurrence` capability covers the construction, assignment, reading, and clearing of `Task.RepetitionRule` values on OmniFocus tasks. The capability exposes a structured schema matching the OmniFocus UI surface: `frequency` (`daily` | `weekly` | `monthly` | `yearly`), `interval` (every N units, ≥1), `daysOfWeek` (weekly only, any subset of the 7 days), and `method` (`fixed` | `dueDate` | `start`). Repetition is set and cleared through `create_task` and `edit_task`; the current rule is returned by `get_task` as structured fields parsed from the underlying RRULE. Raw RRULE strings are not exposed as input — all recurrence is expressed through the structured schema.
+
+#### Scenario: Capability is named and scoped
+- **WHEN** a change proposes adding or modifying recurrence-related behavior
+- **THEN** it lands requirements under this capability
+
+### Requirement: Set repetition rule on task
+
+The system SHALL accept a `repetitionRule` field in `create_task` and `edit_task`. When provided, the snippet SHALL construct an ICS RRULE string from the structured fields and assign it via `new Task.RepetitionRule(rrule, method)`. The `daysOfWeek` field SHALL only be valid when `frequency` is `"weekly"`; providing it for any other frequency SHALL be a validation error. When `edit_task` receives `repetitionRule: null`, the snippet SHALL assign `task.repetitionRule = null` to clear the rule. When `edit_task` omits `repetitionRule` entirely, the existing rule SHALL be left unchanged.
+
+#### Scenario: Set daily repetition at creation
+- **WHEN** `create_task` is called with `{ name: "Stand-up", repetitionRule: { frequency: "daily", interval: 1, method: "fixed" } }`
+- **THEN** the created task has a repetition rule of every day (fixed interval) and the returned TaskDetail includes the parsed repetitionRule
+
+#### Scenario: Set weekly repetition on specific days
+- **WHEN** `create_task` is called with `{ repetitionRule: { frequency: "weekly", interval: 1, daysOfWeek: ["monday", "wednesday", "friday"], method: "start" } }`
+- **THEN** the task repeats every Mon/Wed/Fri from completion date
+
+#### Scenario: Edit task to add repetition
+- **WHEN** `edit_task` is called with `{ id: "t1", repetitionRule: { frequency: "monthly", interval: 1, method: "dueDate" } }`
+- **THEN** the task's repetition rule is set to monthly (due date) and all other fields are unchanged
+
+#### Scenario: Clear repetition via null
+- **WHEN** `edit_task` is called with `{ id: "t1", repetitionRule: null }`
+- **THEN** the task's repetition rule is cleared and `get_task` returns `repetitionRule: null` for that task
+
+#### Scenario: daysOfWeek on non-weekly frequency is a validation error
+- **WHEN** `create_task` or `edit_task` is called with `{ repetitionRule: { frequency: "daily", daysOfWeek: ["monday"], method: "fixed" } }`
+- **THEN** the tool returns a validation error before any snippet executes
+
+### Requirement: Return repetition rule from get_task
+
+The system SHALL include a `repetitionRule` field in the `TaskDetail` returned by `get_task`. When a task has no repetition rule, the field SHALL be `null`. When a task has a rule, the field SHALL be a structured object with `frequency`, `interval`, `daysOfWeek` (omitted when not applicable), and `method`, parsed from the underlying RRULE and RepetitionMethod.
+
+#### Scenario: get_task returns null when no repetition set
+- **WHEN** `get_task` is called for a task with no repetition rule
+- **THEN** the returned TaskDetail includes `repetitionRule: null`
+
+#### Scenario: get_task returns structured repetition fields
+- **WHEN** `get_task` is called for a task with a weekly repetition rule
+- **THEN** the returned TaskDetail includes `repetitionRule` with `frequency: "weekly"`, correct `interval`, `daysOfWeek` array, and `method`

package/openspec/specs/settings/spec.md

@@ -0,0 +1,15 @@
+# settings
+
+## Purpose
+
+Covers reading OmniFocus application settings and preferences via the OmniJS API. Individual tools and the enumeration of writable keys will be defined in the `settings` change.
+
+## Requirements
+
+### Requirement: Capability declared
+
+The `settings` capability SHALL cover reading OmniFocus application settings and preferences where the OmniJS API exposes them. Write access SHALL be limited to the subset of settings that OmniJS documents as writable; the specific writable keys SHALL be enumerated when the `settings` change is drafted. Requirements for individual tools SHALL be added by that change.
+
+#### Scenario: Capability is named and scoped
+- **WHEN** a future change proposes adding settings tools
+- **THEN** it lands requirements under this capability, with an explicit enumeration of writable keys vs read-only keys

package/openspec/specs/tag-management/spec.md

@@ -0,0 +1,39 @@
+# tag-management
+
+## Purpose
+
+Defines tools for reading and listing OmniFocus tags, including hierarchical tag listing and detail retrieval by ID.
+
+## Requirements
+
+### Requirement: List tags
+
+The system SHALL provide a `list_tags` tool that returns tags in the OmniFocus database as an array of summaries, each containing `{id, name, path, parentId, status}`. Tags form a tree in OmniFocus; the `path` field SHALL use the canonical ` ▸ ` separator and represent the full ancestor chain. The `parentId` field SHALL be `null` for top-level tags. The `status` field SHALL be one of `"active" | "onHold" | "dropped"`. The tool SHALL accept an optional `status` filter string and an optional `limit` integer (default 200). When `status` is omitted, all tags are returned regardless of status. When `limit` is omitted, at most 200 tags are returned.
+
+#### Scenario: All tags returned by default
+- **WHEN** `list_tags` is called with no arguments
+- **THEN** the tool returns all tags (active, onHold, and dropped) up to the limit
+
+#### Scenario: On-hold tag is reported with correct status
+- **WHEN** the database contains a tag that has been placed on hold
+- **THEN** that tag appears in the result with `status: "onHold"`
+
+#### Scenario: Filter by status returns only matching tags
+- **WHEN** `list_tags` is called with `{ filter: { status: "active" } }`
+- **THEN** only active tags are returned
+
+#### Scenario: Limit caps the number of returned tags
+- **WHEN** `list_tags` is called with `{ limit: 5 }`
+- **THEN** at most 5 tags are returned
+
+### Requirement: Get tag by ID
+
+The system SHALL provide a `get_tag` tool that accepts `{id: string}` and returns the full detail record of the named tag, including `{id, name, path, parentId, status, childTagIds}`. If no tag exists with that ID, the tool SHALL return a structured not-found error.
+
+#### Scenario: Existing tag returns full detail
+- **WHEN** `get_tag` is called with the ID of an existing tag
+- **THEN** the tool returns the tag's full detail including the IDs of its immediate child tags
+
+#### Scenario: Missing tag returns not-found error
+- **WHEN** `get_tag` is called with an ID that does not correspond to any tag
+- **THEN** the tool returns a structured error with a not-found code

package/openspec/specs/tag-write/spec.md

@@ -0,0 +1,49 @@
+## ADDED Requirements
+
+### Requirement: Create tag
+
+The system SHALL provide a `create_tag` tool that creates a new OmniFocus tag and returns its full detail record. The tool SHALL accept `{name: string, parentTagId?: string}`. If `parentTagId` is provided the tag SHALL be created nested under that tag; otherwise it SHALL be created at the top level.
+
+#### Scenario: Create top-level tag
+- **WHEN** `create_tag` is called with `{name: "Waiting"}` and no `parentTagId`
+- **THEN** the tool creates the tag at the top level and returns its full detail record including a stable `id`
+
+#### Scenario: Create child tag
+- **WHEN** `create_tag` is called with `{name: "Email", parentTagId: "abc123"}`
+- **THEN** the tool creates the tag nested under the specified parent tag and returns its full detail record with `path` and `parentId` set correctly
+
+#### Scenario: Non-existent parent tag returns not-found error
+- **WHEN** `create_tag` is called with a `parentTagId` that does not correspond to any tag
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Edit tag
+
+The system SHALL provide an `edit_tag` tool that modifies an existing tag and returns its updated full detail record. The tool SHALL accept `{id: string}` plus any subset of `{name?: string, status?: "active" | "onHold" | "dropped"}`. Fields omitted SHALL be left unchanged.
+
+#### Scenario: Rename a tag
+- **WHEN** `edit_tag` is called with `{id: "abc123", name: "Delegated"}`
+- **THEN** the tag's name is updated and the tool returns the updated detail record
+
+#### Scenario: Put tag on hold
+- **WHEN** `edit_tag` is called with `{id: "abc123", status: "onHold"}`
+- **THEN** the tag's status becomes `"onHold"` and the tool returns the updated detail record
+
+#### Scenario: Non-existent tag returns not-found error
+- **WHEN** `edit_tag` is called with an ID that does not correspond to any tag
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Delete tag
+
+The system SHALL provide a `delete_tag` tool that permanently deletes a tag and all its child tags using OmniJS `deleteObject()`. Tasks and projects that held the tag have it removed automatically by OmniFocus. The tool description SHALL instruct the AI to confirm with the user before invoking, noting that child tags are also deleted.
+
+#### Scenario: Delete a tag
+- **WHEN** `delete_tag` is called with the ID of an existing tag
+- **THEN** the tag is permanently removed from OmniFocus, all tasks that held it have it removed, and the tool returns a confirmation envelope
+
+#### Scenario: Delete tag with children removes entire subtree
+- **WHEN** `delete_tag` is called with the ID of a tag that has child tags
+- **THEN** the tag and all its descendant tags are deleted
+
+#### Scenario: Non-existent tag returns not-found error
+- **WHEN** `delete_tag` is called with an ID that does not correspond to any tag
+- **THEN** the tool returns a structured not-found error

package/openspec/specs/task-filtering/spec.md

@@ -0,0 +1,63 @@
+## ADDED Requirements
+
+### Requirement: Filter list_tasks results
+
+The system SHALL allow `list_tasks` to accept an optional `filter` object that restricts which tasks are returned. All filter fields are optional and combine as AND conditions. When `filter.status` is omitted, the tool SHALL exclude tasks with status `complete` or `dropped` by default.
+
+Filter fields:
+- `flagged` (boolean): when `true`, return only flagged tasks
+- `status` (array of TaskStatus): return only tasks whose status is in the array; overrides the default exclusion of complete/dropped
+- `tagId` (string): return only tasks that have this tag assigned
+- `dueBeforeDate` (ISO datetime string): return only tasks where `dueDate` is non-null and on or before this date
+
+#### Scenario: Filter by flagged
+- **WHEN** `list_tasks` is called with `{ scope: { all: true }, filter: { flagged: true } }`
+- **THEN** the tool returns only tasks where `flagged` is `true`, excluding complete and dropped tasks
+
+#### Scenario: Filter by status array
+- **WHEN** `list_tasks` is called with `{ scope: { all: true }, filter: { status: ["overdue", "dueSoon"] } }`
+- **THEN** the tool returns only tasks with status `overdue` or `dueSoon`
+
+#### Scenario: Filter by tagId
+- **WHEN** `list_tasks` is called with `{ scope: { projectId: "abc123" }, filter: { tagId: "tag456" } }`
+- **THEN** the tool returns only tasks in that project that have the specified tag assigned
+
+#### Scenario: Filter by dueBeforeDate
+- **WHEN** `list_tasks` is called with `{ scope: { all: true }, filter: { dueBeforeDate: "2026-04-09T23:59:59Z" } }`
+- **THEN** the tool returns only tasks with a non-null dueDate on or before the specified date, excluding complete and dropped tasks
+
+#### Scenario: Default excludes complete and dropped
+- **WHEN** `list_tasks` is called with no filter
+- **THEN** the tool returns tasks with any status except `complete` and `dropped`
+
+#### Scenario: Explicit status filter overrides default exclusion
+- **WHEN** `list_tasks` is called with `{ filter: { status: ["complete"] } }`
+- **THEN** the tool returns completed tasks (the default exclusion does not apply)
+
+#### Scenario: Combined filters act as AND
+- **WHEN** `list_tasks` is called with `{ filter: { flagged: true, tagId: "tag456" } }`
+- **THEN** the tool returns only tasks that are both flagged AND have that tag
+
+### Requirement: Limit list_tasks results
+
+The system SHALL allow `list_tasks` to accept an optional `limit` integer that caps the number of tasks returned. When `limit` is omitted, a default of 200 SHALL apply.
+
+#### Scenario: Default limit of 200
+- **WHEN** `list_tasks` is called without a `limit` and more than 200 tasks match
+- **THEN** the tool returns at most 200 tasks
+
+#### Scenario: Custom limit
+- **WHEN** `list_tasks` is called with `{ limit: 50 }`
+- **THEN** the tool returns at most 50 tasks
+
+### Requirement: Enriched task summary includes dueDate and tagIds
+
+The `TaskSummary` returned by `list_tasks` SHALL include `dueDate` (ISO datetime or null) and `tagIds` (array of tag ID strings) in addition to existing fields.
+
+#### Scenario: Summary includes dueDate
+- **WHEN** `list_tasks` returns a task that has a due date set
+- **THEN** the task summary includes `dueDate` as an ISO datetime string
+
+#### Scenario: Summary includes tagIds
+- **WHEN** `list_tasks` returns a task that has tags assigned
+- **THEN** the task summary includes `tagIds` as an array of tag ID strings

package/openspec/specs/task-management/spec.md

@@ -0,0 +1,51 @@
+# task-management
+
+## Purpose
+
+Defines tools for reading and listing OmniFocus tasks, including scoped listing and full detail retrieval by ID.
+
+## Requirements
+
+### Requirement: List tasks with scope filter
+
+The system SHALL provide a `list_tasks` tool that returns tasks within a caller-specified scope. The scope SHALL be one of: `{projectId: string}`, `{folderId: string}` (all tasks in projects under that folder, recursively), `{inbox: true}`, or `{all: true}` (the full flattened task list). The tool SHALL accept an optional `filter` object (see task-filtering spec) and an optional `limit` integer (default 200). The tool SHALL return an array of task summaries, each containing `{id, name, status, flagged, containerId, containerType, dueDate, tagIds}`. When no `filter.status` is provided, tasks with status `complete` or `dropped` SHALL be excluded by default.
+
+#### Scenario: List tasks in a specific project
+- **WHEN** `list_tasks` is called with `{projectId: "abc123"}`
+- **THEN** the tool returns actionable tasks (non-complete, non-dropped) directly or transitively contained in that project, each carrying the project id as `containerId` and `"project"` as `containerType`
+
+#### Scenario: List inbox tasks
+- **WHEN** `list_tasks` is called with `{inbox: true}`
+- **THEN** the tool returns actionable inbox tasks with `containerType` set to `"inbox"`
+
+#### Scenario: Invalid scope is rejected at the TS boundary
+- **WHEN** `list_tasks` is called with `{projectId: "abc", inbox: true}` (mutually exclusive scopes)
+- **THEN** the tool returns a validation error before any snippet executes
+
+### Requirement: Get task by ID
+
+The system SHALL provide a `get_task` tool that accepts `{id: string}` and returns the full detail record of the named task, including `{id, name, note, status, flagged, deferDate, plannedDate, dueDate, completionDate, estimatedMinutes, containerId, containerType, tagIds, parentTaskId, repetitionRule}`. The `plannedDate` field SHALL be `null` when no planned date is set. The `parentTaskId` field SHALL be `null` for top-level tasks and SHALL contain the parent task's `id.primaryKey` for subtasks. The `repetitionRule` field SHALL be `null` when no repetition rule is set, and SHALL be a structured object with `{frequency, interval, daysOfWeek?, method}` when a rule exists. If no task exists with that ID, the tool SHALL return a structured not-found error.
+
+#### Scenario: Existing task returns full detail
+- **WHEN** `get_task` is called with the ID of an existing task
+- **THEN** the tool returns the task's full detail record including all scalar fields, the list of tag IDs assigned to it, `parentTaskId`, `repetitionRule`, and `plannedDate`
+
+#### Scenario: Subtask includes parentTaskId
+- **WHEN** `get_task` is called with the ID of a subtask
+- **THEN** the returned record includes `parentTaskId` set to the parent task's stable ID
+
+#### Scenario: Task without repetition returns null repetitionRule
+- **WHEN** `get_task` is called for a task with no repetition rule
+- **THEN** the returned TaskDetail includes `repetitionRule: null`
+
+#### Scenario: Task with repetition returns structured repetitionRule
+- **WHEN** `get_task` is called for a task that has a repetition rule
+- **THEN** the returned TaskDetail includes `repetitionRule` with `frequency`, `interval`, `method`, and `daysOfWeek` (if applicable)
+
+#### Scenario: Task with planned date returns plannedDate
+- **WHEN** `get_task` is called for a task that has a planned date set
+- **THEN** the returned TaskDetail includes `plannedDate` as an ISO datetime string
+
+#### Scenario: Missing task returns not-found error
+- **WHEN** `get_task` is called with an ID that does not correspond to any task
+- **THEN** the tool returns a structured error with a not-found code and does not throw an unhandled exception