feat(skills): mappa-presentation — display canon for mappa entities

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).
This commit is contained in:
2026-08-25 22:39:46 +03:00
parent d0b8041891
commit dd9e38b2ee
4 changed files with 220 additions and 4 deletions

View File

@@ -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.

View File

@@ -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`.

View File

@@ -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 `#<internal id>`, 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: `<project> · ` 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
Название: <title>
Статус: 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`.

View File

@@ -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`.