# DESIGN — Todoist capture + AI classification (kb#170)

Status: **v1, components 1/2 built + proven; components 3/4 designed, not
built** — written 2026-07-23
Owner: alvis · Written with Claude
Scope: kanboard Adolf task **#170**. Related, not duplicated: Welfare
#102 (proactive-secretary umbrella), #105 (idea capture, pre-Todoist
version of the same need), #106 (people/events reminders).

---

## 1. Why Todoist, and why encoder-only classification

Todoist becomes Adolf's **inbox for ideas and quick tasks** — the place a
thought gets captured immediately, before it's clear whether it's a
one-liner or a project. Two things must stay true per
`DESIGN-a2a-agents.md` v2.1:

- **No metered API by default** (§3a): classification must not spend a
  Kimi/gemma turn per capture. The stack already keeps **bge-m3** resident
  (Hindsight's embedder, never-evict, `model-registry.yaml`) — reusing it
  for classification is ~0 marginal cost, same reasoning §3a already
  applies to LiteLLM's Auto Router.
- **Native commands run before the agent** (proven pattern:
  `quota-command-openclaw-plugin`, kb#62): a `/idea` command that never
  invokes Kimi at all keeps the entire capture path — not just the
  classification step — off the metered/quota-gated path.

So: **nearest-centroid classification over bge-m3 embeddings**, not a
classifier LLM call and not hard tag rules. This is genuinely an
encoder-only model in the literal sense (bge-m3 is an encoder, not a
generative LLM) — no fine-tuning, no training loop, because **no labelled
dataset exists** (inventing one would be guessing scope that wasn't
asked for). The "training data" is a small, git-editable exemplar list per
class (`agap-mcp/src/classifier.js`) — extending accuracy later means
adding exemplars, not retraining.

## 2. Architecture

```
 Matrix "/idea <текст>"                Adolf prose ("запомни идею...")
         |                                        |
         v                                        v
 todoist-capture-plugin              Adolf (Kimi) -> MCP tool call
 (native command, 0 Kimi calls)       todoist_capture_idea (agap-mcp)
         |                                        |
         +--------------------+-------------------+
                               v
                    POST /capture-idea  (agap-mcp, plain REST)
                               |
                               v
                 classifier.js: embed(text) via bge-m3
                 (1 embedding call, reused for all 3 axes)
                               |
              +----------------+----------------+
              v                v                v
         area centroid   urgency centroid  decompose centroid
        (5 classes)        (3 classes)        (2 classes)
              |                |                  |
              +----------------+------------------+
                               v
                    capture.js: label + priority mapping
                               |
                               v
                 todoistCreateTask() -> real Todoist task
                 labels: area-*, urgency-*, [decompose], [area-uncertain]
```

Two entry points converge on one pipeline (`capture.js`'s
`todoistCaptureIdea`), reachable either as an MCP tool
(`todoist_capture_idea`, for Adolf's/Claude's model-driven path — "запомни
идею: ...") or as a plain REST route (`POST /capture-idea`, for the native
`/idea` command, which cannot speak MCP JSON-RPC). Both call the exact
same function — no duplicated classification/creation logic.

## 3. Component 2 — AI classification (built, proven)

Three independent axes per idea, one bge-m3 embedding shared across all
three:

| Axis | Classes | Source of exemplars |
|---|---|---|
| **area** | `adolf`, `welfare`, `дом`, `семья`, `здоровье` (kb#170 spec, verbatim) | `AREA_EXEMPLARS` |
| **urgency** | `high`, `medium`, `low` | `URGENCY_EXEMPLARS` |
| **decompose** | `simple-task`, `needs-decomposition` | `DECOMPOSE_EXEMPLARS` |

Classification = cosine similarity of the idea's embedding against each
class's centroid (mean of that class's exemplar embeddings), argmax per
axis. Each result also carries a **margin** (gap between the top two
scores) and an `ambiguous: true` flag when the margin is small
(< 0.03, an empirical starting threshold — same "tune later" posture as
`DESIGN-proactive-prioritization.md`'s constants). Ambiguous area
classifications get an extra `area-uncertain` label instead of being
silently forced — component 4 (periodic review) is where a human
resolves them, not an auto-retry on a bigger model (consistent with
`DESIGN-a2a-agents.md` §5's always-ask escalation policy, scaled down:
this isn't a costly/irreversible action, so the "escalation" here is just
a label, not a blocking gate to alvis's inbox).

**Proven** (`agap-mcp/src/classifier.test.mjs`, run against the real,
live bge-m3 at `:11436` — 7/7 pass): area/urgency/decompose all resolve
sensibly on hand-written Russian idea text spanning all 5 areas, both
urgency bands, and both decompose classes. `capture.test.mjs` (6/6 pass)
proves the label/priority/project mapping with a **stubbed** Todoist
client — no test data was written to the real Todoist account while
proving this out.

### 3.1 Project vs. label mapping — a decision made, not guessed

Todoist's real, live projects today (`todoist_list_projects`, confirmed
2026-07-23): `Inbox`, `One-Off`, `Family`, `Planning`, `Pending`. These do
**not** line up with the 5 kb#170 areas except `семья` ≈ `Family`.
Creating four new Todoist projects (`Adolf`, `Welfare`, `дом`,
`здоровье`) to match would be a structural change to the user's real
Todoist account — **not done here without sign-off** (see §6, open
question 1). Instead, v1 uses **labels** (`area-*`, `urgency-*`,
`decompose`, `area-uncertain`) for every axis — purely additive and
reversible (Todoist auto-creates labels on first use; deleting a label
loses no task data) — and auto-routes to an existing project only for the
one unambiguous match (`семья` → `Family`), never inventing a project
selection the classifier merely guessed at.

## 4. Component 1 — capture command (built, not activated)

`openai/todoist-capture-plugin/` — same shape as `quota-command-openclaw-
plugin` (kb#62): `definePluginEntry` + `api.registerCommand({ name:
"idea", acceptsArgs: true, requireAuth: true, handler })`. Verified
against the real `PluginCommandHandler`/`PluginCommandContext`/
`OpenClawPluginCommandDefinition` types in the OpenClaw source
(`/home/alvis/adolf/src/plugins/types.ts`) — `ctx.args` is the raw string
after `/idea`, handler returns `{ text, suppressReply }`.

`requireAuth: true` (default) keeps it behind the same Matrix DM allowlist
(`channels.matrix.dm.allowFrom`) gating every other Adolf interaction — no
new privilege tier, since creating a Todoist task in the operator's own
inbox isn't a privileged/destructive action.

**Wired but not live**: `docker-compose.yml` gets the read-only bind mount
(same pattern as `quota-command`/`hindsight-memory`/`kimi-quota-footer`),
`openclaw.json` gets `plugins.entries.todoist-capture.enabled: true`, and
`agap-mcp/src/server.js` gets the `POST /capture-idea` route the plugin
calls. All three are plain config/code edits, proven end-to-end with a
stub Todoist client (see kb#170 report) — but **none of this takes effect
until the adolf container is restarted** (same activation gate every prior
plugin in this repo has hit: bind-mounts and `plugins.entries` are read at
process start). That restart is the kb#170 handoff — see report.

## 5. Component 3 — sync with services (designed, not built)

kb#170's spec: "идеи из Todoist синхронизируются с Kanboard, календарём,
проектами." This is underspecified enough that building a concrete
bidirectional sync now would be guessing scope (direction? conflict
resolution? which Todoist state maps to which Kanboard column?) rather
than following it. **v1 proposal, one-way, human-gated — not built yet:**

- Todoist is the **source of truth for the idea itself** (text, labels,
  done/not-done). Kanboard is the source of truth for **anything that
  became real, tracked work**.
- Sync fires only from component 4's periodic review (§6), not on a
  schedule or webhook: when Adolf proposes "this idea is ready to become
  work" and the human agrees, Adolf creates **one** Kanboard task whose
  description contains a `context ref` back to the Todoist task id (per
  `DESIGN-a2a-agents.md` §2's "context travels by reference" rule — no
  content duplication) and the Todoist task gets a `kanboard-<id>` label
  and stays open until the Kanboard task closes.
- **No calendar sync is proposed in v1.** A Todoist due-date does not
  imply a calendar event (most captured ideas won't have a real due
  time), and the reverse (creating calendar entries from arbitrary idea
  due-dates) risks cluttering Radicale with noise. Calendar involvement
  belongs with Welfare #106's people/events reminders design, not
  invented here.
- **No two-way Kanboard→Todoist sync.** Completing the Kanboard task does
  not need to close the Todoist item automatically for v1 — a human
  glancing at Todoist can see the `kanboard-<id>` label and close it
  manually; automating that closure is a small, safe follow-up once the
  one-way direction above is live and observed, not blocking v1.

This keeps sync a **consequence of the human-gated review** (§6), never
an autonomous background writer to three services at once — consistent
with `DESIGN-a2a-agents.md` §5's always-ask posture for anything crossing
a service boundary. Building this is out of scope for this pass; flagged
in the kb#170 report as a natural follow-up task once components 1/2 are
live and real capture data exists to review.

## 6. Component 4 — periodic review (designed, not built)

"Adolf предлагает, какие идеи созрели для превращения в задачи" — this is
explicitly Adolf proposing, not auto-converting; matches
`DESIGN-a2a-agents.md` §5's always-ask escalation policy exactly (a
decision task to alvis's inbox, not a silent action). Proposed shape,
**not implemented**:

- A low-priority proactive cadence job (same shape as Welfare #124's
  cadence design, once that lands) that runs `todoist_list_tasks` scoped
  to labels `decompose` or `area-uncertain`, drafts a short proposal per
  candidate ("эта идея выглядит готовой к декомпозиции — завести задачу
  в Kanboard?"), and sends it via Matrix — same impact/cost gate as
  `DESIGN-proactive-prioritization.md` (kb#123) should apply here too,
  once that gate exists, rather than inventing a second one.
- On accept: component 3's one-way sync (§5) fires for that one idea.
- On dismiss: the idea's `decompose`/`area-uncertain` label is cleared so
  the same candidate doesn't re-surface every cadence run.

Not built now because it depends on #124 (cadence) and, for a well-
calibrated gate, #123 (impact/cost gate) — both cited as dependencies
rather than duplicated, same posture `DESIGN-proactive-prioritization.md`
itself takes toward its own siblings.

## 7. What's built vs. handed off

| Piece | State |
|---|---|
| `agap-mcp/src/classifier.js` + test | Built, proven live against bge-m3 |
| `agap-mcp/src/capture.js` + test | Built, proven with a stubbed Todoist client (no real writes) |
| `agap-mcp/src/server.js`: `todoist_capture_idea` MCP tool + `POST /capture-idea` | Built; **not live** — needs an agap-mcp rebuild/restart (already true of the whole Todoist tool surface per kb#170 orchestrator note) |
| `adolf/openclaw.json`, `openai/shared-mcp.json`, `openai/agent-registry.yaml` | Edited, `validate_capability_grants.py` passes clean at both layers |
| `openai/todoist-capture-plugin/` (`/idea` command) | Built, HTTP contract proven with a local harness; **not live** — needs the adolf container restarted (bind mount + `plugins.entries` already wired) |
| Component 3 (sync) | Designed (§5), not built — genuine scope decisions flagged, not guessed |
| Component 4 (periodic review) | Designed (§6), not built — depends on Welfare #123/#124 |

## 8. Open questions for alvis (not guessed)

1. **Todoist project structure**: keep the label-only v1 (§3.1), or
   create dedicated Todoist projects per area? The latter is a real,
   visible change to the account structure and needs explicit sign-off.
2. **Activation**: rebuilding agap-mcp (its own repo/compose,
   `agap_git/agap-mcp/docker-compose.yml`, `build: .` — the `Dockerfile`
   `COPY`s `src/` into the image, no bind mount, so a code change needs a
   rebuild, not just a restart) and restarting the adolf container (its
   compose is `agap_git/openai/docker-compose.yml`, to re-read
   `openclaw.json` and pick up the new plugin bind mount) are the two
   outward-facing steps this task deliberately did not take. Exact
   commands, once approved:
   ```
   cd /home/alvis/agap_git/agap-mcp && docker compose build && docker compose up -d
   cd /home/alvis/agap_git/openai && docker compose up -d adolf
   ```