# Tasks & projects: user guide

Tasks turns explicitly submitted work into proposals, tasks, milestones and projects. Your MCP client and the dashboard use the same records. meinKontext stores context and applies deterministic workflows; your external assistant or a person identifies action items.

## Workspaces in the browser

Use the page header to select one of your personal **Workspaces**. **All content** shows everything you may access, including content without a workspace assignment. An empty workspace stays empty. Manage assignments under [Workspaces](/account/workspaces). The selection also applies when navigating, searching and exporting within the plugin. Save unfinished changes before switching workspaces; switching closes the previous editors.

A workspace says where content lives and where an agent works; a bucket says who else may use it. The workspace selection in the browser is not a grant: it widens neither access rights nor MCP credentials. [More about workspaces](/docs/context).

## Start in five minutes

1. Open **Account → Plugins** (`/account/plugins`) and enable **Aufgaben & Projekte / Tasks & projects**. An organization owner or administrator manages activation; this does not give them access to your records.
2. Open **Tasks & projects** (`/account/tasks`), choose a workspace in the page header, or use **All content**.
3. Capture a task with a title; add the desired outcome when refining it. Add a date and an IANA time zone only if a deadline exists.
4. Use **Projects → New project** for a bounded outcome, start and target date. A task list can contain several projects. Assign tasks to a project in their properties; use **Roadmap** to see their dates.
5. Reconnect your MCP client after activation. Ask it to load the Tasks guide with `plugin_context`, then use the existing collection.

Example client request: “In the Website relaunch collection, create a task to review the offer. The result should be a recorded decision. Due 2 October 2026, Europe/Berlin. Do not assign it yet.”

## Plan and track work

New tasks enter the **Backlog**. Refine their outcome, priority, project and labels, then move them to **Ready**. Switch between list and Kanban; change status or priority directly on a row or card. Board columns have independent paging. Canceled tasks stay out of the list, the Kanban and the reports until you choose a status: **Canceled** shows only them, **All, including canceled** everything together; the archive is unaffected. Search, project, priority and label filters use the same authorized data as MCP, and sorting applies before pagination. Save a useful filter combination as a view.

Open a ticket to read its context and activity or add a comment, finding or evidence. Property and description changes append authenticated history. Existing assignment approval, dependencies, evidence requirements and agent leases still apply. A task list is shared as a whole through a bucket; a project groups finite work inside it. Workspaces select your browser view as well as context for MCP connections; they do not replace the task list's permissions.

MCP uses `task.capture`, `task.plan`, and `project.save` through `task_command`; `task_query` accepts `priority`, `planning`, `project_id`, `label` and `sort`. For a new independent project pass `id: null`; omitting `id` retains the legacy collection-wide project plan and its rules.

## Edit in place and move Kanban cards

Click a row or card's priority, project, labels or due date to edit it. Use the edit button beside the title to rename it; the title link opens the ticket. Menu selections save immediately. Press **Enter** to save text/date changes or **Escape** to cancel. Projects edit the same way in **Projects** and on the **Roadmap**: title, status, start and target date on the row; outcome and rules stay on the project page. Milestones offer title, status and target date on the row.

Drag a card by its move handle into another status column. With a keyboard, focus the handle, press **Space**, choose a column with the **arrow keys**, then press **Space** again. **Escape** cancels. Rejected moves, such as completing a task with an unresolved prerequisite, show an error and keep the saved status. Cards within a column follow the selected sort order; drag-and-drop does not establish a manual order.

## Filter, sort and save views

Choose a **Workspace** in the page header. **Project** opens a searchable picker; **No project** finds tasks without a project. Use **Add filter** to combine project, status, priority, assignee, label, deadline, review date, milestone and waiting reason. Criteria apply together: project plus status shows matching tasks in that project.

Click an active filter value to change it, or remove that filter with its remove button. **Reset** clears filters. Changing workspaces clears the previous selection and open editors.

Next to **List / Kanban**, choose the sort order:

| Sort | Order |
|---|---|
| Priority | Urgent first. Editing priority can move the task. |
| Due date | Earliest deadline first. |
| Created | Oldest first. Editing priority does not move the task. |

Filters and sorting survive layout changes and reloads. Bookmark the URL to return to it; a URL grants no access. Where available, use **More → Save filters** for a named view. Reports apply their supported filters. Project and other non-task views do not inherit inappropriate task-only filters.

## Example: prepare a remote workshop

1. Choose a workspace for the workshop, then create a **Remote workshop October** project with a target date. Grant team access separately through sharing; the workspace selection does not share the project.
2. Capture tickets for the Teams group, slides, missions, invitations and participant message. Give each a verifiable outcome, priority, responsibility and any real deadline.
3. Add **Blocked by** for prerequisites and **Related to** for useful previous runs that should not block completion.
4. Ask the agent to work through those tickets and record steps, problems, decisions and result evidence in their activity. Required approvals still apply.
5. Review the result and archive resolved work. For the next run, an agent can compare readable historical tickets and propose an SOP draft. The plugin preserves that history; it does not train agents or generate SOPs itself.

## Update the plugin

When [Plugins](/account/plugins) shows **Update required**, an organization owner or admin can select **Update**. Installed and available versions appear together. Tasks supports a direct upgrade from 0.0.1–0.0.7 to 0.0.8; intermediate installations are unnecessary. Content, existing sharing and access remain unchanged. A disabled plugin stays disabled and can be enabled separately afterward. Reconnect MCP clients after updating.

If an available update has no button, ask an organization owner or admin to apply it. If no reviewed upgrade exists for the installed version, contact platform support.

## Which view should I use?

| View | What it answers |
|---|---|
| All tasks | What work exists in the selected workspace? |
| Backlog | Which captured tasks still need refinement before work starts? |
| My tasks | What has been assigned to me? Unassigned work is not automatically mine. |
| Inbox | Which proposed action items still need acceptance or dismissal? |
| Projects | What is the goal and state of each project? |
| Roadmap | What are the projects' start and target dates? |
| Milestones | What intermediate outcomes and target dates are tracked? |
| Reports | How is the currently filtered work distributed by status? Click a status to open its tasks. |
| Archive | Which resolved records were archived, and can be restored? |

Search covers task titles, outcomes, keys and status notes. Workspace, date, status and responsibility filters narrow the task views. Projects, milestones and proposals do not inherit inappropriate task-only filters. Shared collections from another organization appear with links to their owner scope. If something appears missing, check the selected workspace, owner, view and date filter first.

Saved views retain filters for a collection. Reports and exports respect current access. JSON exports contain canonical plugin files; CSV and Markdown provide filtered task reports. Exports remain restricted to the selected workspace and your current access. These exports are not a portable backup-import workflow.

## From meeting notes to reviewed work

```text
Source → external assistant → proposed action item → your review → task
                                                  ↘ dismiss
```

Ask the client to submit **candidates**, rather than turn every sentence into assigned work. Each candidate has a stable external ID and optional source references. Accepting it creates a task atomically; retrying the same intake must not create duplicates. Acknowledging an assignment notification is a different operation from accepting a proposal or an assignment.

For untrusted transcripts, use the [restricted import launcher](../../docs/plugins/IMPORT-LAUNCHER.md). It obtains a narrow, short-lived credential before giving the source to the external model. Ordinary full-access MCP connections are not automatically restricted by a prompt. Calendar currently has no unattended import profile.

The source reference must point to a real source; do not use the destination collection as its source. If no source reference exists, use an empty list. meinKontext does not transcribe, extract or infer tasks itself.

## Responsibility and access are separate

First grant appropriate access through the collection's access controls or share the **collection** with a bucket. The live container link also covers future records, subject to their protected parents. Then offer a task to a participant. The recipient must explicitly accept or decline; offers expire and can be withdrawn. Material task edits invalidate pending offers.

| Role | Content permissions |
|---|---|
| Reader | Read records and respond to an offer or workflow card addressed to themselves; cannot generally edit tasks. |
| Contributor | Read, create and edit records and run the collection workflow. |

Access management additionally requires current custody and effective rights. A role name, an assignment, a source link or installation administration never bypasses a protected parent or exclusion. Revocation is checked on reads, reports, exports, notifications and retries. Already delivered copies cannot be recalled.

## Dependencies, completion and archive

Tasks can depend on other tasks and be attached to a milestone. Dependency cycles are rejected. An unresolved dependency blocks completion unless an authorized explicit waiver covers it. Edit dependencies through the relationship picker as Blocks / Blocked by, or through MCP. Explicit waivers use MCP.

Statuses are `todo`, `in_progress`, `blocked`, `done` and `canceled`. If a dependency is reopened after completion, the task can warn about the unresolved dependency; it is not silently rewritten. Archive resolved work to remove it from active views. Restore keeps its identity and protection.

## Working state: keys, notes, journal, waiting and leases

These fields exist for teams and agents that hand work back and forth. Author them through MCP (`task_command`, `task_query`); review and answer them in the task detail page.

| Field | Meaning | Command |
|---|---|---|
| `key` | Human handle such as `T-383`, unique within the collection, never reused. Not an access path. | `task.create` with `key` (e.g. when importing) or `keyPrefix` (next free number) |
| `statusNote` | The one sentence that holds now, at most 300 characters. Replaced, never appended. | `task.note`, or `statusNote` on `task.status` |
| `journal` | Append-only entries with time and actor. You write findings, measurements, tests, decisions, corrections, rollouts, evidence and notes; the workflow adds status, lease, waiting, question, check and answer entries itself. | `task.log` |
| `waitingOn` | What the next step waits for: `work`, `decision`, `check` or `action` by a named participant, or a `delivery` / `third_party` without one. | `task.wait` |
| `decision`, `check` | The card the participant sees: a question with 2–6 options (at most one recommended), or check steps with expected results, location and duration. Required exactly for `decision` and `check`. | `task.wait` |
| `evidence` | What proves the result. | `evidence` on `task.status` |
| `claim` | A lease: ID, holder, since, expiry. Own writes carrying the current claimId renew it; while it is active others may only log, answer or respond; once expired anyone may take it over. | `task.claim` with `leaseHours`, `task.release` |

Only the participant a task waits for can answer it (`task.answer`, which needs the same respond permission as an offer). The answer is journaled, the card disappears and the task waits for its holder again. Completing or canceling a task clears waiting state and the lease; the journal keeps both.

A project plan can set rules for its collection with `project.save` `rules`: `requireStatusNote` (every status change needs a note) and `requireEvidence` (completion needs evidence). Rejections name the rule: `STATUS_NOTE_REQUIRED`, `EVIDENCE_REQUIRED`, `CLAIMED`, `KEY_CONFLICT`, `INVALID_WAITING`, `INVALID_DECISION`, `INVALID_ANSWER`.

`task_query` filters by `key`, `waiting_kind` and `waiting_for`; search also covers the key and the status note. Records written before these fields read as empty. After writing a task with them, a rollback to an older server cannot read that task until the newer version returns.

## Deadlines and scheduled work

A due date belongs to Tasks and works without Calendar. It has a date and a time zone; it is not a time reservation.

With both compatible plugins enabled, open a task and use **Plan work time / Arbeitszeit einplanen**. Calendar creates a separate work block referencing that task. The task detail lists currently readable linked events. Scheduling does not change the task's deadline, assignee or status, and completing a task does not cancel its events.

See the [Calendar guide](../plugin-calendar/GUIDE.md#schedule-work-for-a-task) for same-owner restrictions, unlinking and disabled-companion behavior.

## Use an independent agent account

After authenticating that account with personal OAuth, call `list_plugins`, then `plugin_configure({"plugin_id":"meinkontext.tasks","enabled":true})` as its organization owner/admin. Reconnect if the client caches tools. Create collections and use the workflow below entirely through MCP.

To share selected context with another existing account: `create_bucket`, `add_bucket_member` with the exact account email, `plugin_access` to discover the collection's domain roles, then `plugin_link_bucket` with a suitable role. This shares the whole collection, including future records. The recipient discovers both its own and shared collections, using each returned owner organization for subsequent calls. Receiving a collection grants neither custody nor the right to share it onward.

Use `plugin_set_access` for direct grants/exclusions to members of the same organization. Use `remove_bucket_member` to revoke a recipient's bucket access or `plugin_link_bucket` with `role_id: null` to unshare a collection. These changes leave the recipient's private context intact. Restricted import credentials cannot administer plugins or sharing.

## MCP walkthrough

Load `plugin_context({"plugin_id":"meinkontext.tasks"})`, then call `task_collections`. Reuse a returned collection ID and, for shared scopes, its `ownerOrganizationId` as `owner_organization_id`. Your own workspace has one task list, which the host creates with the first write: omit `collection_id` to use it.

Call `task_command` with this request, replacing the placeholder with the actual ID:

```json
{
  "collection_id": "<returned-collection-id>",
  "idempotency_key": "offer-review-create-1",
  "command": {
    "type": "task.create",
    "title": "Review the offer",
    "outcome": "Decision and next step recorded",
    "due": {"kind":"date","date":"2026-10-02","zone":"Europe/Berlin"},
    "sourceRefs": []
  }
}
```

The result includes the task ID. `plugin_get({"id":"<task-id>"})` returns its canonical data and current revision. For an edit, supply `expected_revisions: {"<task-id>": <current-revision>}` with a new idempotency key. Retry an uncertain response with the **same complete request and key**; a changed request with that key conflicts. A revision conflict means reread and reconsider the edit, not blindly resubmit.

| Tool | Use |
|---|---|
| `task_query` | Filter tasks, candidates, project plans, milestones or saved views; returns authorized rows and counts. |
| `task_intake` | Submit a proposal through the narrow intake action; appropriate for restricted imports. |
| `task_command` | Create/edit, review candidates, manage dependencies, milestones, offers and status. |
| `task_participants` | Discover eligible named participants; never guess user IDs. |
| `task_inbox`, `task_acknowledge` | Read assignment notifications and mark them read; neither accepts an offer. |
| `plugin_get`, `plugin_resolve` | Read the canonical record or its published summary under current rights. |
| `plugin_export`, `plugin_archive` | Export, archive or restore; archive requires the current revision. |

The exact schemas returned by tool discovery and `plugin_describe` are authoritative. The public summary is `meinkontext.tasks.task-summary@1.0.0`; it ships with this package in `contracts/`.

## Troubleshooting and limits

- **No tools after activation:** reconnect the MCP client; tool catalogs and initialization instructions may be cached.
- **No scheduling action:** enable compatible Tasks and Calendar in the owner organization and check access. Linking across different owner organizations is not supported.
- **Disabled plugin:** existing authorized data remains readable/exportable; new writes are blocked. Disabling does not delete the data or uninstall the pinned reader.
- **Missing source or task:** ask its custodian for access; a reference does not carry permission.
- **Empty inbox:** it contains pending proposals, not all tasks. Assignment notifications are shown separately.

There is no historical burndown chart, SOP/ticket-template editor, project hierarchy, Gantt/capacity planning, automatic extraction, calendar synchronization, background scheduler or external notification delivery. Messages functionality is a separate optional plugin. See [implementation and evidence](../../docs/plugins/README.md), and [developer contracts](README.md).

## Conversations with Messages

When compatible Messages is enabled in the same organization, detail pages show linked conversations and a discuss action. It opens a question with this record as context. Each recipient needs independent source access; a message grants none. Replies do not change a Task or book an Event. The base plugin remains fully usable without Messages.

### Versioned workflow, review and lease ownership

The Task detail page shows state, waiting/decision/test cards, evidence and journal. An awaited reader can answer their card with an explicit choice; answering never completes the task or sends a message. Card authoring and project-rule configuration use MCP. Quoted third-party approval is not an authenticated answer.

Tasks now write format v6 and retain strict v1–v5 readers; Projects write v2 and retain strict v1 readers. An authorized first edit upgrades the record; read alone does not. The public `task-summary@1.0.0` contract is unchanged for optional Calendar/Messages integrations.

`task.claim` with `leaseHours: 24` returns `claimId`. Retain it for that work session and include it on edits, renewal and release. Foreign logs/answers never renew a lease. A client sharing your account must not adopt another client's discovered ID: the ID coordinates sessions but is not authentication or an access grant. Accepted delegation clears the old lease. Omitting `leaseHours` keeps legacy permanent self-assignment.

Project rules apply to implicit claim/release status changes too. Required policy records must be readable before execution and replay; an inaccessible rule never means “no rule.” Never invent completion evidence or weaken a rule to finish a command.

### Find cards and confirm saved changes

Decision and test cards are fields of a Task, not skills, wiki articles or saved filters. Give the agent both the collection name and human key. For example: “Read T-383's test card in the Website project and record my observation: Only 11 rows are visible.” Recording your observation neither means the agent performed the test nor completes the task.

The MCP path is `plugin_context` → `task_collections` → `task_query` with collection, owner and key. Successful `task_command` calls include the current record and revision read back after writing. The agent should verify the requested fields before confirming a save. Chat text alone does not persist anything. If the write succeeds but the subsequent read is unavailable, report both facts and retry the read instead of creating a duplicate write. [Receipt semantics for client developers](README.md#mcp-write-receipts).

## Context, next steps and review dates

Expand **Context & planning** when creating or editing a task. Context explains why it exists; next steps describe planned work; review date records when to revisit it, with its own time zone. External links accept HTTP(S) URLs and optional labels. Links are not fetched. The outcome remains the success criterion, the status note describes the present and findings belong in the journal.

A review date never changes the delivery deadline, reserves Calendar time or sends a reminder. Search includes context and next steps. **Review** filters unfinished work to revisit today or earlier, supports saved views and applies to reports/CSV exports. JSON still exports the complete authorized collection.

MCP `task.create` / `task.edit` accept `context`, `nextSteps`, `reviewOn` and `links`. Omission preserves existing values on edit; `null` clears text/date and `[]` clears links. Retain existing title/outcome/due/sourceRefs and use current owner, collection and revision. `task_query` accepts `review: "today" | "overdue" | "none" | "any"`.

## Typed task relationships

Open a ticket and choose **Add** under **Task relationships**. Select a type, search for a task, then choose a result. Search reaches readable tasks in the same collection beyond the first page.

| Type | Meaning from the current ticket |
|---|---|
| Related to | Related work without a completion requirement. |
| Parent task | At most one structural parent; it grants no access. |
| Builds on | Prior work without a completion requirement. |
| Blocks | The linked task depends on this ticket. |
| Blocked by | This ticket depends on the linked task. |

Click an existing row's type to change it inline. Its remove button removes only that relationship. Blocks / Blocked by appears inversely on the other ticket. Editing Blocks also requires edit permission on the target.

For example, **Invite participants** is **Blocked by Copy workshop slides**. The slides ticket shows **Blocks Invite participants**. While that prerequisite is unresolved, the invitation task cannot normally complete. An explicitly authorized waiver needs a reason and uses MCP. Changing the relationship to Related to removes the completion requirement.

Parent, builds-on and dependency chains reject cycles. Relationships grant no rights. Missing access for safe cycle checks or a concurrent ticket change rejects the edit. Reload and reconsider before retrying.

MCP `task.relation.edit` changes one relationship. `from: null` adds; `to: null` removes; otherwise `from` and `to` select among `reference`, `parent`, `builds_on`, `blocks`, and `blocked_by`. Read both records first and supply `id`, `targetId`, `targetRevision`, current `expected_revisions`, and applicable own-session lease proofs. `blocks` means the target depends on `id`; `blocked_by` means `id` depends on the target. Other links remain unchanged. The existing `task.relations` and `task.dependencies` commands each replace a full list; preserve unrelated entries when using them.

Calendar and Messages stay optional and retain `task-summary@1.0.0`. Agent service identities remain separate. Historical source import is described below.

## Import a historical task list

The deterministic TASKS.md importer freezes and hashes its input, then creates an isolated collection snapshot without model inference. Keys (including T-001), project labels, original fields/free text, authors and history order are preserved. Original date precision stays intact. Missing outcomes remain null, explicitly “not recorded”.

The detail page separates **original task-list history** from authenticated workflow events. Historical reporter/author strings are not principals. Original claims, waiting states and decision/check cards are preserved as source assertions, never activated as current assignments or approvals. Resolve the report's operational gaps before any cutover.

Only the collection custodian can import, into an empty collection. At most 20 tasks are committed per batch. Interrupted imports resume with the same source; incomplete collections are marked and reject ordinary edits. `task_query(kind="import")` shows progress. Identical retries do not duplicate records; a different snapshot needs another empty collection. `projectLabel` classifies tasks inside the collection without changing access. `task_query(project_label=...)` filters it exactly.

Use the JSON export for complete provenance. The importer compares every projected record and restores the frozen source byte-for-byte. This does not serialize subsequent edits back into TASKS.md. CSV/Markdown remain view reports. [Commands and evidence](https://github.com/Yesterday-AI/context-mcp/blob/main/docs/plugins/TASKS-HISTORY-IMPORT.md).

For reviewed compatible releases, **Manage plugins → Update** explicitly upgrades installation metadata, without rewriting records or widening existing content access. MCP equivalent: inspect `list_plugins`, then `plugin_configure(upgrade_from_version=installedVersion, enabled=...)`. Reconnect clients afterwards. Unsupported migrations fail closed.

MCP search and write receipts defer imported source material into `sourceHistory` counts. Use `plugin_get` for original history; routine searches do not load the entire old task list into the model context.

### Review old cards before adoption

Ask your agent: “In my import collection, review T-42's historical cards. Show missing information and possible identity mappings; do not change anything.”

`task_import_review` separates numbered decisions and conservatively drafts structured checks. Missing expected results, location or duration stay unresolved. Historical names remain source text. An explicitly proposed participant is checked against current collection participants; access does not prove historical authorship.

This review saves nothing. Activating a selected card needs a new explicit `task.wait` request, a fresh revision and current rights/claim proof. Old answers are not new approvals. Terminal tasks, existing active cards and claims are flagged for review.

## Managed agent access

From Tasks 0.0.7 / meinKontext 0.0.116, create agents under [Agents](/account/agents) and explicitly grant a collection and Tasks role. No separate owner accounts or copied context. [Setup and limits](/docs/agents).

Each concurrent worker needs its own credential. A leased claim is bound to its authenticated work session; knowing the visible claim ID cannot transfer it. Managed agents must specify leaseHours when claiming. The journal identifies the actual agent; “Authenticated attribution” reveals non-secret session and credential references. Human identities and old records remain readable.

An agent answers only cards waiting for its own identity, never automatically for its owner. Calendar and Messages are not available through this first managed access profile. A new credential starts a new session and does not inherit active leases.

Revoking a credential leaves its existing lease until expiry. The collection custodian can use **Recover this lease** on the task with an explicit reason. The journal records the custodian and reason; managed agents cannot use this path.


## Copy an existing task collection

The custodian of an empty destination can call `plugin_command` with action
`meinkontext.tasks.collection-copy`. Supply `sourceOrganizationId`,
`sourceCollectionId` and a complete `sourceRevisions` map from a raw source
export. The caller must be able to read every source record, including archived
records. The server reads those records itself; caller-supplied record bodies
are never accepted. Cross-account sources need an existing collection share.

Each call copies up to 25 records. Continue with the returned `copyId` and
`offset` equal to `copiedCount`, keeping the original revision map. Reuse the
same idempotency key only when retrying the same request. A changed source
requires a new empty destination. Normal commands stay blocked until complete.

Task formats, historical journals, dates and import snapshots are retained;
internal task and snapshot IDs are remapped. Active assignments, offers, claims,
workflow controls, project/milestone links, external references, protected
records, attachments and other record formats are refused. Review these before
starting. Historical package revision chains remain in the source collection.
The source is never changed. Managed agents cannot initiate copies; issue their
credentials after granting access to the completed destination.

### Clear a current note or evidence

Use `task.clear` with the task `id` and `fields: ["statusNote"]`,
`["evidence"]` or both. Supply the current task revision in `expected_revisions`
and your `claimId` under an active lease. Unselected fields remain unchanged.
Clearing preserves the journal, status and completion time; it records only
fields that actually changed. An already-empty selection does not create a new
revision, journal entry or lease renewal. Required evidence on a completed task
cannot be cleared. Status-note requirements still apply to status transitions.
A successful write may have unavailable readback: retry an authorized read, not
a new mutation. An identical transport retry uses the same idempotency key.

### Incremental historical reconciliation

For an explicitly commissioned amendment to an already populated collection,
use `plugin_command` with action `meinkontext.tasks.history-reconcile`. A stable
source ID, canonical T-key, explicit native ID and current revisions are required;
never match titles. Preview first, resolve source/native conflicts and apply only
the reviewed digest. Original history stays intact, native-only edits survive,
and current cards require explicit card/person selection. The deterministic CLI
is `pnpm tasks:history-reconcile --help`. See the [contract and recovery procedure](https://github.com/Yesterday-AI/context-mcp/blob/main/docs/plugins/TASKS-HISTORY-RECONCILE.md).
