@scardis/omnifocus-mcp 0.1.0

package/openspec/changes/archive/2026-04-10-planned-date/specs/task-write/spec.md

@@ -0,0 +1,69 @@
+## MODIFIED Requirements
+
+### Requirement: Create task
+
+The system SHALL provide a `create_task` tool that creates a new OmniFocus task and returns its full detail record. The tool SHALL accept `{name: string, note?: string, flagged?: boolean, deferDate?: string, plannedDate?: string, dueDate?: string, estimatedMinutes?: number, projectId?: string, parentTaskId?: string, tagIds?: string[], repetitionRule?: RepetitionRuleInput}`. Placement SHALL be determined as follows: if both `projectId` and `parentTaskId` are provided the tool SHALL return an error; if only `projectId` is provided the task is placed at the project root; if only `parentTaskId` is provided the task is created as a subtask inheriting its parent's project; if neither is provided the task is placed in the inbox. When `repetitionRule` is provided, the task SHALL have the specified recurrence set at creation.
+
+#### Scenario: Create inbox task
+- **WHEN** `create_task` is called with `{name: "Buy milk"}` and no `projectId` or `parentTaskId`
+- **THEN** the tool creates the task in the OmniFocus inbox and returns its full detail record including a stable `id`
+
+#### Scenario: Create task in a project
+- **WHEN** `create_task` is called with `{name: "Write tests", projectId: "abc123"}`
+- **THEN** the tool creates the task at the root of the specified project and returns its full detail record
+
+#### Scenario: Create subtask
+- **WHEN** `create_task` is called with `{name: "Review PR", parentTaskId: "xyz789"}`
+- **THEN** the tool creates the task as a child of the specified parent task and returns its full detail record
+
+#### Scenario: Ambiguous placement is rejected
+- **WHEN** `create_task` is called with both `projectId` and `parentTaskId`
+- **THEN** the tool returns a validation error before any snippet executes
+
+#### Scenario: Non-existent project returns not-found error
+- **WHEN** `create_task` is called with a `projectId` that does not correspond to any project
+- **THEN** the tool returns a structured not-found error
+
+#### Scenario: Create task with repetition rule
+- **WHEN** `create_task` is called with `{ name: "Weekly review", repetitionRule: { frequency: "weekly", interval: 1, method: "start" } }`
+- **THEN** the task is created with the specified recurrence and the returned TaskDetail includes the parsed repetitionRule
+
+#### Scenario: Create task with planned date
+- **WHEN** `create_task` is called with `{ name: "Clean kitchen", plannedDate: "2026-04-15T09:00:00Z" }`
+- **THEN** the task is created with the specified planned date and the returned TaskDetail includes `plannedDate`
+
+### Requirement: Edit task
+
+The system SHALL provide an `edit_task` tool that modifies an existing task and returns its updated full detail record. The tool SHALL accept `{id: string}` plus any subset of `{name?: string, note?: string, flagged?: boolean, deferDate?: string | null, plannedDate?: string | null, dueDate?: string | null, estimatedMinutes?: number | null, tagIds?: string[], repetitionRule?: RepetitionRuleInput | null}`. Fields omitted from the call SHALL be left unchanged. When `tagIds` is provided it SHALL replace the task's entire tag set; when omitted, tags SHALL be unchanged. Passing `null` for a date or `estimatedMinutes` SHALL clear the field. Passing `repetitionRule: null` SHALL clear the task's recurrence; passing a `RepetitionRuleInput` object SHALL set or replace the recurrence; omitting `repetitionRule` SHALL leave the existing recurrence unchanged.
+
+#### Scenario: Edit a single field
+- **WHEN** `edit_task` is called with `{id: "abc123", flagged: true}`
+- **THEN** only the `flagged` field is changed; all other fields retain their previous values
+
+#### Scenario: Replace tag set
+- **WHEN** `edit_task` is called with `{id: "abc123", tagIds: ["t1", "t2"]}`
+- **THEN** the task's tags are set to exactly `["t1", "t2"]`, replacing any previously assigned tags
+
+#### Scenario: Clear a date field
+- **WHEN** `edit_task` is called with `{id: "abc123", dueDate: null}`
+- **THEN** the task's due date is cleared
+
+#### Scenario: Clear planned date
+- **WHEN** `edit_task` is called with `{id: "abc123", plannedDate: null}`
+- **THEN** the task's planned date is cleared
+
+#### Scenario: Non-existent task returns not-found error
+- **WHEN** `edit_task` is called with an ID that does not correspond to any task
+- **THEN** the tool returns a structured not-found error
+
+#### Scenario: Non-existent tag ID returns not-found error
+- **WHEN** `edit_task` is called with a `tagIds` array containing an ID that does not correspond to any tag
+- **THEN** the tool returns a structured not-found error and the task is not modified
+
+#### Scenario: Set repetition via edit
+- **WHEN** `edit_task` is called with `{ id: "t1", repetitionRule: { frequency: "monthly", interval: 1, method: "dueDate" } }`
+- **THEN** the task's recurrence is set and all other fields are unchanged
+
+#### Scenario: Clear repetition via edit
+- **WHEN** `edit_task` is called with `{ id: "t1", repetitionRule: null }`
+- **THEN** the task's recurrence is cleared and all other fields are unchanged

package/openspec/changes/archive/2026-04-10-planned-date/tasks.md

@@ -0,0 +1,26 @@
+## 1. Schema changes (src/schemas/)
+
+- [x] 1.1 Add `plannedDate: z.string().datetime().optional()` to `CreateTaskInput` in `shapes.ts`
+- [x] 1.2 Add `plannedDate: z.string().datetime().nullable().optional()` to `EditTaskInput` in `shapes.ts`
+- [x] 1.3 Add `plannedDate: z.string().datetime().nullable()` to `TaskDetail` in `shapes.ts`
+
+## 2. Snippet updates (src/snippets/)
+
+- [x] 2.1 Update `create_task.js`: set `task.plannedDate` when provided; include `plannedDate: isoOrNull(task.plannedDate)` in returned TaskDetail
+- [x] 2.2 Update `edit_task.js`: set/clear `task.plannedDate` using same pattern as deferDate/dueDate; include in returned TaskDetail
+- [x] 2.3 Update `get_task.js`: include `plannedDate: isoOrNull(task.plannedDate)` in returned detail
+- [x] 2.4 Update `complete_task.js`: include `plannedDate: isoOrNull(task.plannedDate)` in returned TaskDetail
+- [x] 2.5 Update `drop_task.js`: include `plannedDate: isoOrNull(task.plannedDate)` in returned TaskDetail
+
+## 3. Integration tests (test/integration/)
+
+- [x] 3.1 `plannedDate.int.test.ts`: create task with plannedDate; verify get_task returns it
+- [x] 3.2 `plannedDate.int.test.ts`: edit task to set plannedDate; verify get_task reflects it
+- [x] 3.3 `plannedDate.int.test.ts`: edit task to clear plannedDate (null); verify get_task returns null
+- [x] 3.4 `plannedDate.int.test.ts`: create task without plannedDate; verify get_task returns null (backward compat)
+
+## 4. Verification
+
+- [x] 4.1 `npm run typecheck` clean
+- [x] 4.2 `npm test` (unit suite) clean
+- [x] 4.3 Manually run integration suite

package/openspec/changes/archive/2026-04-10-task-recurrence/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-10

package/openspec/changes/archive/2026-04-10-task-recurrence/design.md

@@ -0,0 +1,81 @@
+## Context
+
+OmniFocus tasks carry a `Task.RepetitionRule` which combines an ICS RRULE string with a `RepetitionMethod` enum (`Fixed`, `DueDate`, `Start`). The OmniJS API is:
+- `task.repetitionRule = new Task.RepetitionRule(rruleString, method)` — set
+- `task.repetitionRule = null` — clear
+- `task.repetitionRule.ruleString` — read the RRULE back
+- `task.repetitionRule.method` — read the method back
+
+The OmniFocus UI exposes: frequency (daily/weekly/monthly/yearly), interval (every N units), days-of-week (weekly only), and repeat method (fixed interval / due date / completion date). This change targets exactly that surface.
+
+## Goals / Non-Goals
+
+**Goals:**
+- `create_task`: accept optional `repetitionRule` to set recurrence at creation
+- `edit_task`: accept optional `repetitionRule` (nullable to clear) on existing tasks
+- `get_task` / `TaskDetail`: return current repetition as structured fields (or null)
+- Validate that `daysOfWeek` is only meaningful on `frequency: "weekly"`
+
+**Non-Goals:**
+- RRULE patterns not reachable from the OmniFocus UI (e.g., "every 2nd Tuesday of the month", end-by-count, end-by-date)
+- Project repetition (projects don't have `repetitionRule` in OmniJS)
+- Raw RRULE escape hatch — scope is UI surface only
+
+## Decisions
+
+### Decision 1: Structured schema, no raw rrule
+
+Input schema uses structured fields (`frequency`, `interval`, `daysOfWeek`, `method`). The snippet constructs the RRULE internally via `new Task.RepetitionRule(rruleString, methodEnum)`. This keeps the API LLM-friendly and prevents invalid RRULE strings from being passed in.
+
+Considered: raw `{ rrule, method }` input. Rejected because LLMs may produce invalid RRULE syntax, and the UI surface is small enough to model fully without an escape hatch.
+
+**OmniJS API notes (discovered empirically):**
+- Constructor: `new Task.RepetitionRule(rrule, method)` — NOT `.make()`
+- `Task.RepetitionMethod.Fixed` — fixed interval
+- `Task.RepetitionMethod.DueDate` — repeat from due date
+- `Task.RepetitionMethod.DeferUntilDate` — repeat from completion date (maps to our `"start"` method)
+- Enum values have no `.name` property; use `String(enumValue)` which returns e.g. `"[object Task.RepetitionMethod: DeferUntilDate]"`
+
+### Decision 2: RepetitionRuleInput is its own schema, embedded in CreateTaskInput and EditTaskInput
+
+```
+RepetitionRuleInput = z.object({
+  frequency: z.enum(["daily", "weekly", "monthly", "yearly"]),
+  interval: z.number().int().positive().default(1),
+  daysOfWeek: z.array(z.enum(["sunday","monday","tuesday","wednesday","thursday","friday","saturday"])).optional(),
+  method: z.enum(["fixed", "dueDate", "start"]),
+})
+.refine(d => !d.daysOfWeek || d.frequency === "weekly", {
+  message: "daysOfWeek is only valid when frequency is 'weekly'"
+})
+```
+
+In `EditTaskInput`: `repetitionRule: RepetitionRuleInput.nullable().optional()` — omit to leave unchanged, `null` to clear, object to set.
+
+### Decision 3: Read side returns structured fields parsed from RRULE
+
+`TaskDetail.repetitionRule` is `RepetitionRuleDetail | null`:
+```
+RepetitionRuleDetail = z.object({
+  frequency: z.enum(["daily","weekly","monthly","yearly"]),
+  interval: z.number(),
+  daysOfWeek: z.array(...).optional(),
+  method: z.enum(["fixed","dueDate","start"]),
+})
+```
+
+The snippet parses `task.repetitionRule.ruleString` using simple regex/split to extract FREQ, INTERVAL, and BYDAY. If parsing fails (unsupported RRULE set outside the UI), return `{ rrule: rawString, method }` as a fallback with a `_raw: true` flag — this way the LLM sees something rather than crashing.
+
+### Decision 4: RRULE construction in snippet, not TypeScript
+
+Keeps the logic next to the OmniJS API call. TypeScript layer only validates the structured input and passes it through.
+
+### Decision 5: daysOfWeek maps to BYDAY abbreviations
+
+Day mapping: sunday→SU, monday→MO, tuesday→TU, wednesday→WE, thursday→TH, friday→FR, saturday→SA. When `daysOfWeek` is absent for a weekly rule, no `BYDAY` component is added (repeats on the same weekday as the task's due/defer date).
+
+## Risks / Trade-offs
+
+- **Tasks without a due or defer date + Fixed method**: OmniFocus behavior is undefined (no anchor date). Document in tool description; not validated by the schema.
+- **RRULE parsing on read**: Simple regex parsing covers the UI surface; complex patterns set via OmniJS directly will hit the `_raw` fallback.
+- **interval default**: Schema defaults `interval` to 1 but it must be passed explicitly in the RRULE string (`INTERVAL=1`) — OmniFocus requires it.

package/openspec/changes/archive/2026-04-10-task-recurrence/proposal.md

@@ -0,0 +1,28 @@
+## Why
+
+OmniFocus tasks support repeat intervals, but the MCP server has no way to set, edit, or read repetition rules — forcing users to manually configure recurrence in OmniFocus after every task creation. This gap means AI-driven task creation is incomplete for any workflow that involves repeating tasks.
+
+## What Changes
+
+- `create_task`: add optional `repetitionRule` field to set recurrence at creation time
+- `edit_task`: add optional `repetitionRule` field (nullable to clear recurrence) on existing tasks
+- `get_task` / `TaskDetail`: return current `repetitionRule` as structured fields (or null if none)
+- New `RepetitionRuleInput` and `RepetitionRuleDetail` schemas covering the OmniFocus UI surface: frequency, interval, optional days-of-week (weekly only), and repeat method
+
+## Capabilities
+
+### New Capabilities
+
+- `recurrence`: Requirements for reading and writing OmniFocus task repetition rules (frequency, interval, daysOfWeek, method). Note: the `recurrence` spec already exists as a placeholder — this change fills it in.
+
+### Modified Capabilities
+
+- `task-write`: `create_task` and `edit_task` gain a `repetitionRule` parameter
+- `task-management`: `get_task` returns `repetitionRule` in `TaskDetail`
+
+## Impact
+
+- `src/schemas/shapes.ts`: new `RepetitionRuleInput` and `RepetitionRuleDetail` types; `CreateTaskInput`, `EditTaskInput`, `TaskDetail` extended
+- `src/schemas/index.ts`: new exports
+- `src/snippets/create_task.js`, `edit_task.js`, `get_task.js`: snippet updates
+- No breaking changes — all new fields are optional; existing callers unaffected

package/openspec/changes/archive/2026-04-10-task-recurrence/specs/recurrence/spec.md

@@ -0,0 +1,47 @@
+## MODIFIED 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
+
+## ADDED Requirements
+
+### 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 `Task.RepetitionRule.make(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/changes/archive/2026-04-10-task-recurrence/specs/task-management/spec.md

@@ -0,0 +1,25 @@
+## MODIFIED Requirements
+
+### 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, dueDate, completionDate, estimatedMinutes, containerId, containerType, tagIds, parentTaskId, repetitionRule}`. 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`, and `repetitionRule`
+
+#### 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: 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

package/openspec/changes/archive/2026-04-10-task-recurrence/specs/task-write/spec.md

@@ -0,0 +1,61 @@
+## MODIFIED Requirements
+
+### Requirement: Create task
+
+The system SHALL provide a `create_task` tool that creates a new OmniFocus task and returns its full detail record. The tool SHALL accept `{name: string, note?: string, flagged?: boolean, deferDate?: string, dueDate?: string, estimatedMinutes?: number, projectId?: string, parentTaskId?: string, tagIds?: string[], repetitionRule?: RepetitionRuleInput}`. Placement SHALL be determined as follows: if both `projectId` and `parentTaskId` are provided the tool SHALL return an error; if only `projectId` is provided the task is placed at the project root; if only `parentTaskId` is provided the task is created as a subtask inheriting its parent's project; if neither is provided the task is placed in the inbox. When `repetitionRule` is provided, the task SHALL have the specified recurrence set at creation.
+
+#### Scenario: Create inbox task
+- **WHEN** `create_task` is called with `{name: "Buy milk"}` and no `projectId` or `parentTaskId`
+- **THEN** the tool creates the task in the OmniFocus inbox and returns its full detail record including a stable `id`
+
+#### Scenario: Create task in a project
+- **WHEN** `create_task` is called with `{name: "Write tests", projectId: "abc123"}`
+- **THEN** the tool creates the task at the root of the specified project and returns its full detail record
+
+#### Scenario: Create subtask
+- **WHEN** `create_task` is called with `{name: "Review PR", parentTaskId: "xyz789"}`
+- **THEN** the tool creates the task as a child of the specified parent task and returns its full detail record
+
+#### Scenario: Ambiguous placement is rejected
+- **WHEN** `create_task` is called with both `projectId` and `parentTaskId`
+- **THEN** the tool returns a validation error before any snippet executes
+
+#### Scenario: Non-existent project returns not-found error
+- **WHEN** `create_task` is called with a `projectId` that does not correspond to any project
+- **THEN** the tool returns a structured not-found error
+
+#### Scenario: Create task with repetition rule
+- **WHEN** `create_task` is called with `{ name: "Weekly review", repetitionRule: { frequency: "weekly", interval: 1, method: "start" } }`
+- **THEN** the task is created with the specified recurrence and the returned TaskDetail includes the parsed repetitionRule
+
+### Requirement: Edit task
+
+The system SHALL provide an `edit_task` tool that modifies an existing task and returns its updated full detail record. The tool SHALL accept `{id: string}` plus any subset of `{name?: string, note?: string, flagged?: boolean, deferDate?: string | null, dueDate?: string | null, estimatedMinutes?: number | null, tagIds?: string[], repetitionRule?: RepetitionRuleInput | null}`. Fields omitted from the call SHALL be left unchanged. When `tagIds` is provided it SHALL replace the task's entire tag set; when omitted, tags SHALL be unchanged. Passing `null` for a date or `estimatedMinutes` SHALL clear the field. Passing `repetitionRule: null` SHALL clear the task's recurrence; passing a `RepetitionRuleInput` object SHALL set or replace the recurrence; omitting `repetitionRule` SHALL leave the existing recurrence unchanged.
+
+#### Scenario: Edit a single field
+- **WHEN** `edit_task` is called with `{id: "abc123", flagged: true}`
+- **THEN** only the `flagged` field is changed; all other fields retain their previous values
+
+#### Scenario: Replace tag set
+- **WHEN** `edit_task` is called with `{id: "abc123", tagIds: ["t1", "t2"]}`
+- **THEN** the task's tags are set to exactly `["t1", "t2"]`, replacing any previously assigned tags
+
+#### Scenario: Clear a date field
+- **WHEN** `edit_task` is called with `{id: "abc123", dueDate: null}`
+- **THEN** the task's due date is cleared
+
+#### Scenario: Non-existent task returns not-found error
+- **WHEN** `edit_task` is called with an ID that does not correspond to any task
+- **THEN** the tool returns a structured not-found error
+
+#### Scenario: Non-existent tag ID returns not-found error
+- **WHEN** `edit_task` is called with a `tagIds` array containing an ID that does not correspond to any tag
+- **THEN** the tool returns a structured not-found error and the task is not modified
+
+#### Scenario: Set repetition via edit
+- **WHEN** `edit_task` is called with `{ id: "t1", repetitionRule: { frequency: "monthly", interval: 1, method: "dueDate" } }`
+- **THEN** the task's recurrence is set and all other fields are unchanged
+
+#### Scenario: Clear repetition via edit
+- **WHEN** `edit_task` is called with `{ id: "t1", repetitionRule: null }`
+- **THEN** the task's recurrence is cleared and all other fields are unchanged

package/openspec/changes/archive/2026-04-10-task-recurrence/tasks.md

@@ -0,0 +1,39 @@
+## 1. Schema changes (src/schemas/)
+
+- [x] 1.1 Define `RepetitionRuleInput` zod schema: `{ frequency, interval (default 1), daysOfWeek?, method }` with `.refine()` that daysOfWeek is only valid when frequency is "weekly"
+- [x] 1.2 Define `RepetitionRuleDetail` zod schema: `{ frequency, interval, daysOfWeek?, method }` (no refine needed — read-only)
+- [x] 1.3 Add `repetitionRule: RepetitionRuleInput.optional()` to `CreateTaskInput`
+- [x] 1.4 Add `repetitionRule: RepetitionRuleInput.nullable().optional()` to `EditTaskInput`
+- [x] 1.5 Add `repetitionRule: RepetitionRuleDetail.nullable()` to `TaskDetail`
+- [x] 1.6 Export `RepetitionRuleInput` and `RepetitionRuleDetail` from `src/schemas/index.ts`
+
+## 2. Snippet updates (src/snippets/)
+
+- [x] 2.1 Update `create_task.js`: after task creation, if `args.repetitionRule` is provided, construct RRULE string from frequency/interval/daysOfWeek and call `Task.RepetitionRule.make(rrule, method)`; include `repetitionRule` in returned TaskDetail
+- [x] 2.2 Update `edit_task.js`: if `args.repetitionRule === null` assign `task.repetitionRule = null`; if `args.repetitionRule` is an object, construct and assign the rule; if `args.repetitionRule` is undefined, leave unchanged; include `repetitionRule` in returned TaskDetail
+- [x] 2.3 Update `get_task.js`: read `task.repetitionRule`; if null return `null`; otherwise parse `ruleString` (extract FREQ, INTERVAL, BYDAY via string ops) and map method enum to string; return structured `repetitionRule` field
+
+## 3. Helper: RRULE construction and parsing
+
+- [x] 3.1 In `create_task.js` and `edit_task.js`: implement `buildRrule(rule)` helper that produces the RRULE string — `FREQ=X;INTERVAL=N` plus `BYDAY=MO,WE,...` when daysOfWeek is present
+- [x] 3.2 In `create_task.js`, `edit_task.js`, and `get_task.js`: implement `parseRepetitionRule(rule)` helper that reads `rule.ruleString` and `rule.method`, extracts FREQ/INTERVAL/BYDAY via string split, maps back to structured fields
+
+## 4. Unit tests (test/unit/)
+
+- [x] 4.1 Add schema tests for `RepetitionRuleInput`: valid daily; valid weekly with daysOfWeek; valid monthly; valid yearly; invalid daysOfWeek on non-weekly frequency rejected; interval must be positive integer
+- [x] 4.2 Add schema tests for extended `CreateTaskInput`: valid with repetitionRule; valid without (backward compat)
+- [x] 4.3 Add schema tests for extended `EditTaskInput`: valid with repetitionRule object; valid with repetitionRule null (clear); valid omitting repetitionRule (unchanged)
+
+## 5. Integration tests (test/integration/)
+
+- [x] 5.1 `taskRecurrence.int.test.ts`: create task with daily repetition; verify get_task returns repetitionRule with frequency "daily"
+- [x] 5.2 `taskRecurrence.int.test.ts`: create task with weekly repetition on Mon/Wed/Fri; verify get_task returns correct daysOfWeek
+- [x] 5.3 `taskRecurrence.int.test.ts`: edit existing task to add monthly repetition; verify get_task reflects new rule
+- [x] 5.4 `taskRecurrence.int.test.ts`: edit task to clear repetition (null); verify get_task returns repetitionRule: null
+- [x] 5.5 `taskRecurrence.int.test.ts`: create task without repetitionRule; verify get_task returns repetitionRule: null (backward compat)
+
+## 6. Verification
+
+- [x] 6.1 `npm run typecheck` clean
+- [x] 6.2 `npm test` (unit suite) clean
+- [x] 6.3 Manually run integration suite

package/openspec/config.yaml

@@ -0,0 +1,20 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours

package/openspec/specs/attachments/spec.md

@@ -0,0 +1,15 @@
+# attachments
+
+## Purpose
+
+Covers listing, reading, adding, and removing file attachments on task notes via the OmniJS `FileWrapper` API. Individual tools and on-wire encoding decisions will be defined in the `attachments` change.
+
+## Requirements
+
+### Requirement: Capability declared
+
+The `attachments` capability SHALL cover listing, reading, adding, and removing file attachments on task notes via the OmniJS `FileWrapper` API. The on-wire representation of attachment contents across the MCP boundary (inline base64, filesystem path reference, or a hybrid with a size threshold) SHALL be decided when the `attachments` 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 attachment tools
+- **THEN** it lands requirements under this capability and makes the on-wire encoding decision explicit

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

@@ -0,0 +1,15 @@
+# batch-operations
+
+## Purpose
+
+Covers batch variants of every mutating tool with typed-array validation, partial-success semantics, and single-snippet execution. Individual tools will be defined in the `batch-operations` change.
+
+## Requirements
+
+### Requirement: Capability declared
+
+The `batch-operations` capability SHALL cover batch variants of every mutating tool (create, update, delete, move, complete, assign). Batch tools SHALL accept strictly typed arrays validated at the TypeScript boundary (never serialized JSON strings) and SHALL return a per-item result array with partial-success semantics: each element is an `{ok, data?, error?}` envelope carrying that item's outcome independent of other items. Batch tools SHALL execute as a single OmniJS snippet that iterates internally, not as a loop of per-item bridge invocations. Requirements for individual batch tools SHALL be added by the `batch-operations` change.
+
+#### Scenario: Capability is named and semantics are fixed
+- **WHEN** a future change proposes adding batch tools
+- **THEN** it lands requirements under this capability with typed-array validation and partial-success result semantics as invariants

package/openspec/specs/database-inspection/spec.md

@@ -0,0 +1,15 @@
+# database-inspection
+
+## Purpose
+
+Covers scoped, paged, and filtered traversal of the full OmniFocus database, including a `dump_database` tool, inbox inspection, and database metadata. Individual tools will be defined in the `forecast-and-inspection` change.
+
+## Requirements
+
+### Requirement: Capability declared
+
+The `database-inspection` capability SHALL cover scoped, paged, and filtered traversal of the full OmniFocus database, including a `dump_database` tool that accepts `{scope, id?, include, format}` parameters, inbox inspection, and database metadata (name, sync status, object counts). The default behavior of `dump_database` SHALL exclude completed tasks, dropped entities, and task notes to keep payloads manageable; those are opt-in via the `include` parameter. 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 database-inspection tools
+- **THEN** it lands requirements under this capability rather than inventing a new capability name

package/openspec/specs/execution-runtime/spec.md

@@ -0,0 +1,75 @@
+# execution-runtime
+
+## Purpose
+
+Defines the contract for executing OmniFocus domain operations through the OmniJS/JXA bridge, including snippet injection, result protocol, caching, and timeouts.
+
+## Requirements
+
+### Requirement: OmniJS execution via JXA bridge
+
+The system SHALL execute every OmniFocus domain operation inside OmniFocus's OmniJS runtime by invoking `Application('OmniFocus').evaluateJavascript(snippet)` from a JXA host process spawned via `osascript -l JavaScript`. The JXA host SHALL NOT invoke any OmniFocus scripting-dictionary method other than `evaluateJavascript` for domain operations.
+
+#### Scenario: Tool invocation routes through the bridge
+- **WHEN** a tool handler invokes the runtime with a snippet and args
+- **THEN** the runtime spawns `osascript -l JavaScript`, passes a JXA wrapper that calls `Application('OmniFocus').evaluateJavascript` with the prepared snippet, and awaits stdout
+
+#### Scenario: Scripting-dictionary domain methods are forbidden
+- **WHEN** a contributor adds a tool handler that calls e.g. `Application('OmniFocus').defaultDocument.projects` directly
+- **THEN** a unit test (or review) flags the call as a runtime-contract violation and the change is rejected
+
+### Requirement: Snippet argument injection via JSON literal
+
+The system SHALL construct executable scripts by replacing exactly one `__ARGS__` placeholder in a static `.js` snippet template with the result of `JSON.stringify(args)`. No other interpolation of user-supplied data into script source is permitted anywhere in the codebase.
+
+#### Scenario: Apostrophes and quotes survive injection
+- **WHEN** a tool is invoked with `args = {name: "Finn's \"birthday\""}`
+- **THEN** the executed snippet receives `args.name === "Finn's \"birthday\""` and no syntax error occurs
+
+#### Scenario: Unicode and newlines survive injection
+- **WHEN** a tool is invoked with `args = {note: "line1\nline2 — emoji 🎯"}`
+- **THEN** the executed snippet receives the note verbatim including the newline and unicode code points
+
+#### Scenario: Snippets are standalone and paste-ready
+- **WHEN** a developer opens any file under `src/snippets/`
+- **THEN** the file is a valid JavaScript program that can be pasted into OmniFocus's Automation Console after replacing `__ARGS__` with a hand-written object literal, with no additional preprocessing required
+
+### Requirement: One-line JSON result protocol
+
+The system SHALL represent every bridge invocation's result as exactly one line of JSON on the JXA host's stdout, matching the envelope `{ok: true, data: <value>} | {ok: false, error: {name: string, message: string, stack?: string}}`. The TypeScript runtime SHALL read stdout, extract the first JSON-parseable line, and return the parsed envelope to the caller. A result envelope with `ok: false` SHALL be thrown as a structured error with the error details preserved.
+
+#### Scenario: Successful operation returns data envelope
+- **WHEN** a snippet completes without throwing and its final expression is `JSON.stringify({ok: true, data: {id: "abc"}})`
+- **THEN** the TS runtime receives `{ok: true, data: {id: "abc"}}` and returns `{id: "abc"}` to the tool handler
+
+#### Scenario: Snippet exception produces error envelope
+- **WHEN** a snippet throws an `Error` with message "not found"
+- **THEN** the JXA shim catches the exception, prints `{ok: false, error: {name: "Error", message: "not found", ...}}` as one line on stdout, and the TS runtime throws a structured error carrying the name, message, and stack
+
+#### Scenario: Extraneous stdout chatter does not corrupt results
+- **WHEN** any process in the pipeline writes incidental non-JSON output to stdout before the result line
+- **THEN** the TS runtime still parses the result envelope correctly by selecting the first complete JSON-parseable line
+
+### Requirement: Snippet loader
+
+The system SHALL load snippet templates from `src/snippets/<name>.js` relative to the compiled server's known snippet root, caching the file contents in memory after the first read. The loader SHALL reject snippets that do not contain exactly one `__ARGS__` token.
+
+#### Scenario: Snippet is loaded and cached
+- **WHEN** a tool handler invokes the runtime with snippet name `"list_projects"` twice in the same process
+- **THEN** the file `list_projects.js` is read from disk exactly once and the cached content is used for the second invocation
+
+#### Scenario: Snippet with zero placeholders is rejected
+- **WHEN** a snippet file contains no `__ARGS__` token
+- **THEN** the loader throws a contract violation at load time, not at runtime
+
+#### Scenario: Snippet with multiple placeholders is rejected
+- **WHEN** a snippet file contains two or more `__ARGS__` tokens
+- **THEN** the loader throws a contract violation at load time
+
+### Requirement: Script timeout
+
+The system SHALL enforce a configurable per-invocation timeout on `osascript` execution, defaulting to 30 seconds, and SHALL terminate the child process and throw a timeout error when exceeded.
+
+#### Scenario: Long-running snippet is terminated
+- **WHEN** a snippet runs longer than the configured timeout
+- **THEN** the runtime sends SIGTERM to the `osascript` process and throws a timeout error identifying the snippet name and elapsed time

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

@@ -0,0 +1,39 @@
+# folder-management
+
+## Purpose
+
+Defines tools for reading and listing OmniFocus folders, including full folder listing and detail retrieval by ID.
+
+## Requirements
+
+### Requirement: List folders
+
+The system SHALL provide a `list_folders` tool that returns folders in the OmniFocus database as an array of summaries, each containing `{id, name, path, parentId, status}`. The `path` field SHALL use the canonical ` ▸ ` separator and SHALL equal the folder's name for top-level folders. The `parentId` field SHALL be `null` for top-level folders. The `status` field SHALL be one of `"active" | "dropped"`. The tool SHALL accept an optional `status` filter string and an optional `limit` integer (default 200). When `status` is omitted, all folders are returned regardless of status. When `limit` is omitted, at most 200 folders are returned.
+
+#### Scenario: All folders returned by default
+- **WHEN** `list_folders` is called with no arguments
+- **THEN** the tool returns all folders (active and dropped) up to the limit
+
+#### Scenario: Top-level folders have null parent
+- **WHEN** a folder exists at the root of the folder hierarchy
+- **THEN** its summary carries `parentId: null` and `path` equal to its name
+
+#### Scenario: Filter by status returns only matching folders
+- **WHEN** `list_folders` is called with `{ filter: { status: "active" } }`
+- **THEN** only active folders are returned
+
+#### Scenario: Limit caps the number of returned folders
+- **WHEN** `list_folders` is called with `{ limit: 5 }`
+- **THEN** at most 5 folders are returned
+
+### Requirement: Get folder by ID
+
+The system SHALL provide a `get_folder` tool that accepts `{id: string}` and returns the full detail record of the named folder, including `{id, name, path, parentId, status, childFolderIds, projectIds}`. If no folder exists with that ID, the tool SHALL return a structured not-found error.
+
+#### Scenario: Existing folder returns full detail with children
+- **WHEN** `get_folder` is called with the ID of an existing folder
+- **THEN** the tool returns the folder's full detail including the IDs of its immediate child folders and immediate child projects
+
+#### Scenario: Missing folder returns not-found error
+- **WHEN** `get_folder` is called with an ID that does not correspond to any folder
+- **THEN** the tool returns a structured error with a not-found code

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

@@ -0,0 +1,45 @@
+## ADDED Requirements
+
+### Requirement: Create folder
+
+The system SHALL provide a `create_folder` tool that creates a new OmniFocus folder and returns its full detail record. The tool SHALL accept `{name: string, parentFolderId?: string}`. If `parentFolderId` is provided the folder SHALL be created nested inside that folder; otherwise it SHALL be created at the top level.
+
+#### Scenario: Create top-level folder
+- **WHEN** `create_folder` is called with `{name: "Work"}` and no `parentFolderId`
+- **THEN** the tool creates the folder at the top level and returns its full detail record including a stable `id`
+
+#### Scenario: Create nested folder
+- **WHEN** `create_folder` is called with `{name: "Active", parentFolderId: "abc123"}`
+- **THEN** the tool creates the folder inside the specified parent folder and returns its full detail record with `path` reflecting the full ancestor chain
+
+#### Scenario: Non-existent parent folder returns not-found error
+- **WHEN** `create_folder` is called with a `parentFolderId` that does not correspond to any folder
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Edit folder
+
+The system SHALL provide an `edit_folder` tool that renames an existing folder and returns its updated full detail record. The tool SHALL accept `{id: string, name: string}`.
+
+#### Scenario: Rename a folder
+- **WHEN** `edit_folder` is called with `{id: "abc123", name: "Personal"}`
+- **THEN** the folder's name is updated and the tool returns the updated detail record with the new name reflected in `path`
+
+#### Scenario: Non-existent folder returns not-found error
+- **WHEN** `edit_folder` is called with an ID that does not correspond to any folder
+- **THEN** the tool returns a structured not-found error
+
+### Requirement: Delete folder
+
+The system SHALL provide a `delete_folder` tool that permanently and recursively deletes a folder, all child folders, all projects within those folders, and all tasks within those projects. The tool description SHALL instruct the AI to confirm with the user before invoking, explicitly stating that the entire subtree — child folders, projects, and all tasks — is permanently deleted and cannot be undone.
+
+#### Scenario: Delete a folder and all its contents
+- **WHEN** `delete_folder` is called with the ID of an existing folder
+- **THEN** the folder, all descendant folders, all projects within those folders, and all tasks within those projects are permanently removed from OmniFocus and the tool returns a confirmation envelope
+
+#### Scenario: Delete empty folder
+- **WHEN** `delete_folder` is called with the ID of a folder that contains no projects or child folders
+- **THEN** the folder is removed and the tool returns a confirmation envelope
+
+#### Scenario: Non-existent folder returns not-found error
+- **WHEN** `delete_folder` is called with an ID that does not correspond to any folder
+- **THEN** the tool returns a structured not-found error