# duun Agent Guide

duun is a task app for primitive standalone tasks. Use this guide when helping
someone connect an AI assistant, coding agent, or MCP client to duun.

## Core Model

- A task is a standalone unit of work.
- Do not invent projects, lists, folders, labels, tags, areas, collections, or
  similar grouping concepts unless the user explicitly asks for them.
- Task schedules are personal to the authenticated user's task membership.
- Calendar sync is optional, user-controlled, and attached to task schedules.
- Shared-task participants may have their own schedules; treat those schedules
  as participant context, not as a global task schedule.

## Integration Surfaces

- MCP endpoint: https://duun.app/mcp
- Agent setup page: https://duun.app/agents
- Manual setup: create a scoped MCP token in duun Settings, under Integrations.
- OAuth is only for managed integrations explicitly configured by duun. Do not use
  OAuth for general agent setup unless duun's setup page names that client as a
  managed OAuth integration.
- Managed ChatGPT app access uses OAuth and may enforce an app-specific reviewed
  tool policy in addition to normal scope checks.

## MCP Scopes

- `tasks:read`: Read my tasks - List and inspect tasks visible to your account.
- `tasks:create`: Create new tasks - Add tasks, including subtasks, on your behalf.
- `tasks:edit`: Edit task titles - Rename tasks and update task titles while keeping notes and dates separate.
- `tasks:notes`: Edit task notes - Replace, append, and clear task notes.
- `tasks:schedule`: Schedule tasks - Set, clear, or shift your personal schedule for tasks.
- `tasks:move`: Move and reorder tasks - Change task order or move tasks under another task.
- `tasks:complete`: Complete and reopen tasks - Mark tasks done or not done.
- `tasks:delete`: Delete tasks - Remove tasks from your account.
- `tasks:share`: Share tasks - Create invites or grant task access to other people.

Request the smallest useful scope set. `tasks:read` is the baseline read scope.
Mutating scopes should be requested only when the user wants the assistant to make
those changes in duun. Manual MCP tokens use the selected scopes directly. Managed
app integrations may additionally filter tools through an app policy.

## MCP Implementation Boundary

MCP is a standalone integration context. It can share low-level task mutation
and query helpers with app-facing code, but MCP should own its own scope checks,
argument validation, error mapping, tool payloads, broadcasts, and agent activity
recording. Prefer explicit MCP orchestration, even with some duplication, over
routing MCP through UI/app context functions that bundle user-facing side effects.

## Suggested Agent Rule

Users can add this rule to custom instructions, an `AGENTS.md` file, or a similar
agent rule surface:

> Use duun as task memory when I ask task-status or next-action questions and I do
> not specify another tool or source. This includes phrases like "what's next?",
> "what should I do next?", "where were we?", "what are we working on?", "what is
> left?", "what is pending?", "continue", "resume", "pick this back up", "what
> tasks are open?", or similar task/project-status phrasing.
>
> If duun MCP is available, call the relevant duun read/list/search tools before
> answering, or alongside repo/git checks when code context is also needed. If duun
> MCP is unavailable, say that and fall back to chat, repo, or other available
> context.
>
> Respect duun's model: tasks are standalone primitive tasks. Do not invent
> projects, lists, folders, labels, tags, areas, collections, or similar grouping
> concepts unless I explicitly ask.
>
> Use lowercase "duun" in product copy.

## Managed ChatGPT App Surface

The public ChatGPT app should expose only the reviewed tool surface for its current
release. The v1 surface may include task read, create, edit, notes, schedule, move,
complete, delete, and share actions when the user grants the matching scopes.

Keep calendar sync controls, task tree reschedule, and broad bulk update tools out
of the public ChatGPT app surface until each flow is reviewed for user intent,
confirmation behavior, and privacy impact. General MCP clients may still use
available tools according to their manual token scopes.

## MCP Scheduling And Calendar Sync

- `duun__task_schedule` sets or clears the authenticated user's personal schedule.
- `duun__task_calendar_sync_options` lists sanitized calendar sync options and
  status for one task.
- `duun__task_calendar_sync_update` enables or disables calendar sync for the
  authenticated user's task membership on one calendar connection.
- `duun__task_calendar_sync_retry` queues a retry for the authenticated user's
  scheduled task.
- These tools require `tasks:schedule`. Calendar sync tool payloads must not
  expose OAuth tokens, provider event IDs, provider calendar IDs, internal user
  IDs, internal membership IDs, or private participant details.
- Calendar sync controls are not part of the public ChatGPT v1 surface until
  separately reviewed.

## Keeping This Guide Current

Maintainers should update this guide and `/llms.txt` when duun changes MCP/OAuth
integration behavior, available scopes, task or schedule semantics, calendar sync
behavior, privacy-relevant integration details, or the user setup flow for AI tools.

## Assistant Behavior

- Use lowercase "duun" in user-facing product copy.
- Ask for explicit confirmation before destructive actions such as deleting tasks.
- Before deleting a task that may have subtasks, inspect or summarize the tree and
  explain the nested work that will be deleted before calling the delete tool.
- Treat vague cleanup wording as a clarification prompt. Do not archive, delete,
  or complete tasks from vague cleanup wording until the user chooses a specific
  cleanup action.
- For next-action answers, prefer incomplete tasks with no incomplete subtasks.
  Do not present a parent task as next while it still has incomplete children.
- Preserve user wording in task titles and notes unless the user asks for cleanup.
- When scheduling, update the current user's schedule for the task rather than a
  task-level global schedule.
- Do not log or expose OAuth tokens, MCP tokens, task content, calendar metadata,
  or private participant details.
- Prefer concise task titles and put longer context in notes.
- Use Markdown only where the target field supports Markdown notes.

## User-Facing Setup Summary

1. Sign in to duun.
2. Open Settings.
3. Open Integrations.
4. Create a scoped MCP token with the permissions the assistant needs.
5. Configure the MCP client with the duun MCP endpoint and use the token as a
   Bearer token.
6. Verify setup by listing duun MCP tools.

See also:

- Privacy Policy: https://duun.app/privacy
- Terms of Service: https://duun.app/terms
- Subprocessors: https://duun.app/subprocessors