> For the complete documentation index, see [llms.txt](https://docs.holons.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.holons.io/software/tasks.md).

# Tasks

The **Tasks** domain in `@holons/core/tasks` is the most-used part of the system. It implements the **Quest** model: a single shape that covers tasks, proposals, events, offers, and requests, with the same lifecycle—create, accept participants, complete, recognize—applied uniformly.

A user opening the [Telegram bot](/software/holonsbot.md) and typing `/task do the dishes` and a Claude agent calling the MCP `task_create` tool are doing exactly the same thing: producing a Quest in the holon's `tasks` lens.

## Why "Quest" and not "Task"

Early on the system distinguished tasks, proposals, events, offers, and requests as separate types. They had different shapes, different lifecycle hooks, different UIs. The cost was significant: every new feature had to be replicated four times, every UI had four separate views, every aggregator special-cased on type.

The Quest model unifies them. They are still **conceptually** distinct (a `type` field still records what kind of work this is), but the data shape, persistence path, and operation surface are identical. The benefit is concrete: implementing appreciation, completion tracking, federation, or REA-event emission once covers all five.

## The Quest shape

```ts
interface Quest {
  id?: string | number;
  title: string;
  description?: string;

  status: 'ongoing' | 'completed' | 'cancelled' | 'scheduled'
        | 'recurring' | 'repeating' | 'pending' | 'stopped' | string;
  type?: 'task' | 'quest' | 'event' | 'proposal' | 'recurring' | string;
  category?: string;

  // Schedule
  when?: string;     // ISO timestamp
  ends?: string;
  location?: string;

  // People
  participants: QuestParticipant[];
  appreciation?: any[];

  // Provenance
  created?: string;            // ISO from web
  date?: number;               // ms epoch from Telegram
  initiator?: QuestInitiator;

  // Ordering / dependencies (used by quest-tree / council pipelines)
  orderIndex?: number;
  dependsOn?: string[];

  _meta?: QuestMeta;
  _deleted?: boolean;

  // Open shape so existing call sites read/write extra fields safely
  [key: string]: any;
}
```

The shape is deliberately **open**: extra fields are preserved across writes. This is what let the unification happen without forcing every UI to give up data it cared about. The Telegram bot still writes `message_thread_id`, `stoppers`, `dependencies`, `frequency`, `timeTracking`; the web app still writes its richer schedule fields; both continue to work.

Schedule fields (`when`, `ends`, `location`) come from the web side. Telegram-side metadata sits alongside under the open index. A Quest written by either UI is fully readable by both.

## Special quest forms

Two structures wrap the Quest model for higher-order workflows:

### QuestTree (recursive backcasting)

A directed graph of nested quests, used by the **AI council backcasting** flow. Each node is a quest that is both a parent (of finer-grained sub-quests) and a child (of a coarser vision-level goal). The root captures the long-term vision; leaves are immediately-actionable steps.

```ts
interface QuestTree {
  vision: { statement, principles, targetDate?, successIndicators };
  nodes: Record<string, QuestTreeNode>;
  rootNodeIds: string[];
  maxGenerations: number;
  branchingFactor: number;
  headAdvisor: string;
  resourceFlows?: Array<{ fromNodeId, toNodeId, resourceType, description }>;
}
```

Each node carries holonic metadata—skills required, resources required, impact category (`ecological` / `social` / `economic` / `spiritual` / `technical`), success metrics, future state—so a generated tree captures not just the work but the reasoning behind it.

### RitualSession → design streams

A ritual session produces a `wish_statement`, `declared_values`, a panel of advisors (real / mythic / archetype), and a set of **design streams**. `createTasksFromDesignStreams()` turns each stream into a Quest, preserving the link back to the ritual that birthed it.

This is how the system bridges **practice** (ceremony, ritual) and **execution** (tasks): the practice produces an artifact; the artifact decomposes into the work.

## Operations

Grouped by file:

**Creation (`creation.ts`)**

| Function                                | Purpose                                  |
| --------------------------------------- | ---------------------------------------- |
| `createDefaultTask(input)`              | Construct a Quest with sensible defaults |
| `createTaskFromStep(step, ctx)`         | Make a Quest from a design-stream step   |
| `createTasksFromDesignStreams(session)` | Bulk-create from a `RitualSession`       |
| `createTasksFromQuestTree(tree)`        | Bulk-create from a `QuestTree`           |
| `createTaskRecord(input)`               | Lowest-level constructor — pure          |

Constants: `COUNCIL_INITIATOR`, `DEFAULT_TASK_CATEGORY`.

**Participants (`participants.ts`)** — all pure, all return a new Quest:

| Function                           | Purpose                  |
| ---------------------------------- | ------------------------ |
| `addParticipant(task, user)`       | Join                     |
| `removeParticipant(task, userId)`  | Leave                    |
| `toggleParticipant(task, user)`    | Convenience toggle       |
| `addAppreciation(task, user)`      | Recognize a contribution |
| `removeAppreciation(task, userId)` | Undo                     |
| `toggleAppreciation(task, user)`   | Convenience toggle       |

**Completion (`completion.ts`, `completion-plan.ts`, `completion-execute.ts`)**

| Function                            | Purpose                                                                                  |
| ----------------------------------- | ---------------------------------------------------------------------------------------- |
| `applyTaskCompletion(task)`         | Pure: mark a Quest completed                                                             |
| `planTaskCompletion(task, ctx)`     | Compute the side effects of completion (REA events, scoring deltas, dependency cascades) |
| `executeCompletionPlan(plan, deps)` | Run the planned side effects                                                             |

The plan/execute split lets a caller **preview** what completing a Quest will do—what events get emitted, who gets points, which dependent quests unblock—before actually applying it. The MCP server exposes both halves as separate tools so an agent can confirm before committing.

**Persistence (`persistence.ts`)**

| Function                                         | Purpose                |
| ------------------------------------------------ | ---------------------- |
| `saveTaskToHolon(holosphere, holonId, task)`     | Persist a single Quest |
| `saveTasksToHolon(holosphere, holonId, tasks[])` | Persist multiple       |

The HoloSphere interface required is minimal (`HoloSphereLike`)—just `put` and optionally `get`—so the persistence layer is testable with simple in-memory mocks.

## Lifecycle in one picture

```
   createDefaultTask / createTaskFromStep
              │
              ▼
       Quest in memory
              │
              ▼          ┌─────────────────────┐
   addParticipant ─────► │  Quest in memory    │ ◄───── addAppreciation
   toggleParticipant     │  (pure updates)     │        toggleAppreciation
                         └──────────┬──────────┘
                                    │
                                    ▼
                          saveTaskToHolon
                                    │
                                    ▼
                          Quest in HoloSphere
                                    │
                                    ▼
                          planTaskCompletion
                                    │
                                    ▼
                          executeCompletionPlan
                                    │
                                    ▼
                          REA events + score updates +
                          dependency cascade
```

Every step except the persistence and execute calls is pure—so live previews (the web dashboard showing "if you complete this, you and Laura each get 2 points") are cheap.

## MCP tool surface

The [MCP server](/software/mcp-server.md) exposes **10 tools** in the `tasks` domain — the full lifecycle (create, save, participants, appreciation, plan, complete) plus reads. An agent connected via MCP can drive any quest from creation to completion entirely through tool calls.

## See also

* [Council](/software/council.md) — proposals are a Quest type with extra voting machinery
* [Scoring](/software/scoring.md) — how completed quests and appreciations turn into points
* [REA Accounting](/software/rea-accounting.md) — the event ledger that records the side effects of completion
* [HolonsBot](/software/holonsbot.md) — the most-used Quest interface


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.holons.io/software/tasks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.