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:
@@ -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.
|
||||
|
||||
@@ -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`.
|
||||
|
||||
212
skills/mappa-presentation/SKILL.md
Normal file
212
skills/mappa-presentation/SKILL.md
Normal 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`.
|
||||
@@ -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`.
|
||||
|
||||
Reference in New Issue
Block a user