From dd9e38b2ee6c0938750aaba5620a2e15cd027b30 Mon Sep 17 00:00:00 2001 From: vitya Date: Tue, 25 Aug 2026 22:39:46 +0300 Subject: [PATCH] =?UTF-8?q?feat(skills):=20mappa-presentation=20=E2=80=94?= =?UTF-8?q?=20display=20canon=20for=20mappa=20entities?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Agents rendered mappa entities ad-hoc (raw JSON, random fields) — human re-asked 'give me details'. New skill fixes the presentation layer: row (lists) + card (single entity) templates per type, fixed field order, local-time dates (UTC storage, agent converts), full refs, never raw JSON. mappa-task-work/messaging/knowledge now point to it (mandatory format); versions bumped (1.4.1/1.4.1/1.5.1). --- skills/mappa-knowledge/SKILL.md | 3 +- skills/mappa-messaging/SKILL.md | 3 +- skills/mappa-presentation/SKILL.md | 212 +++++++++++++++++++++++++++++ skills/mappa-task-work/SKILL.md | 6 +- 4 files changed, 220 insertions(+), 4 deletions(-) create mode 100644 skills/mappa-presentation/SKILL.md diff --git a/skills/mappa-knowledge/SKILL.md b/skills/mappa-knowledge/SKILL.md index c4a995c..3821a73 100644 --- a/skills/mappa-knowledge/SKILL.md +++ b/skills/mappa-knowledge/SKILL.md @@ -1,7 +1,7 @@ --- name: mappa-knowledge author: ours -version: 1.5.0 +version: 1.5.1 description: > The cycle of working with a project's knowledge in Mappa (Karpathy LLM Wiki, channel = mappa entities): ingest → query → lint + a graph layer for @@ -275,3 +275,4 @@ page already exists; don't proliferate catalog duplicates. - Tree/umbrellas: `mcp__mappa__graph_tree(root, depth?, fields?, limit?)`. - Tasks: `mappa-task-work`. Mail: `mappa-messaging`. Delegation: `mappa-delegation`. - Related: `using-projects-meta` (bridge until the flip), `project-discipline`. +- Showing wiki pages to the human (rows/cards): `mappa-presentation` — mandatory format. diff --git a/skills/mappa-messaging/SKILL.md b/skills/mappa-messaging/SKILL.md index 16b82f9..60406b0 100644 --- a/skills/mappa-messaging/SKILL.md +++ b/skills/mappa-messaging/SKILL.md @@ -1,7 +1,7 @@ --- name: mappa-messaging author: ours -version: 1.4.0 +version: 1.4.1 description: > The inter-session mail cycle via Mappa: SEND (inbox_send) → RECEIVE (inbox_monitor) → POLICY (peer ≠ authority). Address = the project folder @@ -258,4 +258,5 @@ All these flags = **stop and ask the human** (or create a task/wiki page). - Tasks: `mappa-task-work` (board = `mcp__mappa__task_*`). - Handoff: `mappa-closing-ritual` (write) / `mappa-session-orient` (read). - Delegation: `mappa-delegation` (the "board + covering letter" pair). +- Showing letters to the human (rows/cards): `mappa-presentation` — mandatory format. - Related: `recommend-dont-menu` (response style), `project-discipline`. diff --git a/skills/mappa-presentation/SKILL.md b/skills/mappa-presentation/SKILL.md new file mode 100644 index 0000000..5ecc05b --- /dev/null +++ b/skills/mappa-presentation/SKILL.md @@ -0,0 +1,212 @@ +--- +name: mappa-presentation +author: ours +version: 1.0.0 +description: > + The single standard for showing Mappa entities to the human — the answer + format an agent renders for the eyes: list rows (board/inbox/search) and + full cards (one entity). Two modes, fixed field order, dates shown in the + session's local time (converted from mappa UTC), never raw JSON. Mandatory + for ANY display of mappa entities + (task/inbox/wiki/brainstorm/session/handoff/repo/commit/operator/project) — + «покажи таски», «что на досках», «письма», «какой статус», «дай + подробнее», any answer carrying entities. Old name — trigger-synonym: + mappa-display. Complements (does not replace) convention #1028 (ref + format), task status emoji (mappa-task-work), search cards (wiki:2661); + server-side display/card fields (when they arrive) are copied verbatim — + the templates here are the canon fallback. +--- + +# mappa-presentation + +The single standard for **what the human sees** when an agent shows Mappa +entities. Problem it solves: agents rendered entities "as it happened" (raw +JSON dumps, random field sets, slug without number), the human guessed and +re-asked "give me more details". Here — the mandatory format. + +Channel — output to the human in chat. NOT about tools and NOT about data — +about presentation. + +## Hard principles + +1. **Never show raw JSON** of a tool result. Any answer about an entity is + rendered per the templates below. Dumping JSON into chat = bug. +2. **Two modes:** `row` (lists: board, inbox, search results — one line per + entity) and `card` (a single entity on request or when detailing — a full + block). +3. **The card carries ALL fields** of the template. Do not trim "to avoid + clutter": the human re-asks precisely because a field was dropped. +4. **Field order is fixed** (per template), do not rearrange. +5. **Dates — stored UTC, shown local and human.** Mappa stores and returns + UTC (canonical machine truth — the server never converts). The agent renders + in the session's local timezone (the operator's machine): + row `YYYY-MM-DD`, card `YYYY-MM-DD HH:MM` — no seconds, no milliseconds, + no `T`/`Z`. Zone marker (e.g. `(+03:00)`) — optional, at most once per + card; omit in a single-machine setup. If the local timezone is unknown to + the agent — show UTC with an explicit `Z`. Never invent a zone. +6. **Refs always full-name** (`task:N`, `inbox:N`, `wiki:N`, … — convention + #1028), never `#`, never short aliases. + +## Server-side display/card fields (priority) + +When mappa starts returning ready-made `display` (row) and `card` (markdown +block) fields on entities — **copy them verbatim** in the matching mode +(row/card). The templates below are the canon fallback and for composing +lists until server fields exist. If a server field exists but looks broken — +render per template and mention the discrepancy. + +--- + +## Task + +### Row (board/list) + +``` +🔴 task:1062 mappa-task-work — P1 · due 2026-08-30 · созд. 2026-08-24 +``` + +Order: status emoji, ref, slug (title only if shorter than ~50 chars), +project (only in cross-project lists: ` · ` after the slug), +priority, due (if any), created date. Dependencies — suffix `· ← task:1060` +(parent, if present). Overdue — mark `(просрочена)`. + +### Card + +``` +🔴 task:1062 mappa-task-work +Проект: .workshop +Название: +Статус: active · Приоритет: P1 · Дедлайн: 2026-08-30 (просрочена) +Владелец: <owner> +Создана: 2026-08-24 18:25 · Обновлена: 2026-08-25 19:18 +Родитель: task:1060 <parent-slug> +Блокер: <only when status=blocked — what blocks> +Описание: +<first ~15 lines of markdown; end — «… ещё N строк»> +``` + +## Inbox (letter) + +### Row (inbox/list) + +``` +inbox:2257 · от mappa · 2026-08-25 · «1169 — дубль (закрыта), 1171 — done» — обе P2 закрыты… +``` + +Order: ref, `от <from>`, date, subject in quotes, then body teaser (first +~80 chars). If subject is empty — the body teaser replaces it. + +### Card + +``` +📬 inbox:2257 · от mappa +Тема: «<subject>» +Дата: 2026-08-25 17:54 +Отправитель: <sender_display> +--- +<body — first ~20 lines of markdown; end — «… ещё N строк»> +``` + +## Wiki + +### Row + +``` +wiki:2656 AGENTS (.workshop) — обновл. 2026-08-25 +``` + +### Card + +``` +wiki:2656 AGENTS (.workshop) +Заголовок: <title> +Summary: <frontmatter summary, one line> +Обновлена: 2026-08-25 19:18 +--- +<body — first ~20 lines; «… ещё N строк»> +``` + +## Brainstorm (buffer) + +### Row + +``` +brainstorm:14 mappa-presentation (.workshop) — buffer · обновл. 2026-08-25 +``` + +### Card — like wiki, plus `Статус: buffer | archive`. + +## Session + +### Row + +``` +session:742 (vitya) — deepseek-v4-flash · clean · 2026-08-25 +``` + +Order: ref, project, model, end_state (clean | active | stale), date. + +## Handoff + +### Row + +``` +handoff:12 (.workshop) — active · «<summary up to ~100 chars>» +``` + +## Repo / Commit + +### Row + +``` +commit:0e3c55a (pi-extensions) — «README переписан» · 2026-08-25 +``` + +## Operator / Project + +### Row + +``` +operator:vitya — owner · DESKTOP-NSEF0UK +project:83 mappa — role: app +``` + +--- + +## List rules + +- **Tasks:** sort 🔴 → 🟡 → ⚪ → 🔵 → 🟢; inside — by due (overdue first), + then by created. Cross-project — grouped by project, project mandatory. +- **Inbox:** newest first (latest first). +- **Search/cross-project:** project mandatory in every row. + +## Prose rules + +- First mention in text — «slug/name (task:N)» (convention #1028). +- In letters between agents — global number `#N` (format v2, mappa-messaging); + in chat with the human — per-type refs `task:N`. + +## What NOT to do + +- Dump JSON into chat. +- Card with dropped fields "for brevity". +- List row without ref / without status / without date. +- Invented timezones or "yesterday/today" instead of dates. +- ISO `…T…Z` timestamps with seconds in chat — show local `YYYY-MM-DD HH:MM`. +- Internal id instead of ref, short aliases (`t:`/`w:`) instead of full names. +- Trimming body without the «… ещё N строк» marker. + +## Red flags + +- About to paste a tool's output into chat as-is → stop, render per template. +- Human re-asked "give more details" about an entity → a field was dropped + from the card; return the full template. + +--- + +## Reference + +- Ref format: convention #1028 (mappa), full names `task:`/`wiki:`/`inbox:`/… +- Task status emoji: `mappa-task-work`. +- Search cards: `mcp__mappa__search` / `wiki_search` (wiki:2661). +- Task work: `mappa-task-work`. Mail: `mappa-messaging`. Wiki: `mappa-knowledge`. diff --git a/skills/mappa-task-work/SKILL.md b/skills/mappa-task-work/SKILL.md index 2ad83e1..090b514 100644 --- a/skills/mappa-task-work/SKILL.md +++ b/skills/mappa-task-work/SKILL.md @@ -1,7 +1,7 @@ --- name: mappa-task-work author: ours -version: 1.4.0 +version: 1.4.1 description: > The central cycle of working with tasks in Mappa: orientation → work selection (priority/due) → execution → handover (close + review-umbrella) + @@ -99,7 +99,8 @@ Don't confuse: 🟢 — *done*, not "ready". Ready is ⚪. 1. **Inbox sweep** — `mcp__mappa__inbox_monitor(project=<name>)`: unread letters may change the plan. Handle each per `mappa-messaging`. 2. **Board** — `entity_search(q, type='task', project=<name>, limit=50)`: sort - by status (🔴 → 🟡 → ⚪), one line per task, quote the slug. + by status (🔴 → 🟡 → ⚪), one line per task — row format from + `mappa-presentation` (never raw JSON). 3. If the user named a task — `entity_get(key)` by its ref/uuid (`task:NNN` or uuid; task:1067 — bare numbers rejected). 4. Confirm in one sentence: "We're in the middle of X, next step — Y". 5. Ask whether the plan is right before acting. @@ -323,4 +324,5 @@ parks to 🔵 (`no backend for weight_tier: unknown`). Ordinary code → - Session finish (handoff write): `mappa-closing-ritual`. - Session start (pull/handoff/inbox/snapshot): `mappa-session-orient`. - Promotion: `mappa-brainstorm-promote` (review-umbrella for promotions). +- Showing tasks to the human (rows/cards): `mappa-presentation` — mandatory format. - Cross-project overview: `using-system-snapshot` (liveness) / `mcp__projects-meta__tasks_aggregate`.