Claude

---
name: mirador
description: |
  mirador — share AI-generated artifacts on git. Activate IMMEDIATELY when
  the user pastes an @mirador-invitation, @mirador-request, or
  @mirador-response block, or starts a session inside a mirador workspace
  or a `.mirador-link` directory. On a paste, the skill loads the artifact
  context FIRST (via WebFetch of the read-only doc), then delivers a
  brain-shaped brief — it does not ask the user what to do.
---

# mirador

The user's **brain** is their agent's own living memory — the context *you*
already carry (your memory, their `CLAUDE.md` / `AGENTS.md`). Mirador never keeps
a separate brain store; `mirador brain` shows read-only what it resolves, and you
read it natively. It shapes how you read the artifacts they open. Same artifact,
personal lens. Never share it across users; it never enters git or a handoff.

## Activation contract — important

**When the user pastes a seed, the skill ACTS. It does not ask which option
to pick.** Pasting an `@mirador-invitation` is the user telling you: *open
this for me.* Asking "should I fetch?" or listing 1/2/3 options before
loading the artifact is wrong — the user already made the decision when
they pasted.

The right shape:

> *Pasted @mirador-invitation. Loading…*
> *[fetch the read-only doc, parse the body]*
> *[surface a one-screen brief, brain-shaped]*
> *[then, and only then, offer concrete next steps]*

The wrong shape:

> *I see this is an invitation. I could (a) WebFetch, (b) open in browser,
> (c) wait. Which would you like?*

Never the wrong shape. The pastes are unambiguous; act on them.

## Activation signals

Trigger this skill if **any** of the following fire:

| Signal | What to do |
|---|---|
| User pastes a block starting with `@mirador-invitation` | 1. Parse the seed for `Artifact`, `From`, `Role expected`, `Note`, `Read-only:`, `Repo:`. 2. WebFetch the `Read-only:` URL silently. 3. Read your own memory (the brain). 4. Synthesise a one-screen brief in their voice — lead with what they would check first. 5. Then offer concrete next steps (refine, comment, decline). |
| User pastes a block starting with `@mirador-request` | Parse the seed. Surface the ask (what is requested + by when + role). Offer `accepted` / `declined` decision with one-line consequence each. Do not load any external URL — requests do not carry an artifact yet. |
| User pastes a block starting with `@mirador-response` | Parse the seed. Update the originating request's state in `~/.mirador/workspace/outgoing-requests/<slug>.md`. Surface the response in the next `mirador inbox`. |
| Working directory contains `.mirador-link` | The artifact was promoted to a shared repo. Resolve the link's `repo` field; open the shared clone at `clone_path` instead of the workspace folder. |
| Working directory is a mirador workspace | Read the brain. Use it to frame the session — what the user usually checks first, who they author for, their domain language. |
| User invokes `/mirador` slash command | If the buffer contains a seed, treat it as a seed paste. Otherwise run paste-driven onboarding. |

## Workflow on an invitation paste — onboard to refine

The invitation **onboards the recipient to refine**, zero manual setup. The seed
carries the repo + the three steps. The only human act is the paste.

1. **Parse the seed.** Extract `Artifact`, `From`, `Role expected`, `Note`,
   `Repo:` URL, `Read-only:` URL. Missing required field → surface the error, stop.
2. **Onboard to refine (T2 — the default).** Execute, in order, no ceremony:
   - install if missing: `npm i -g mirador-cli` (skip if `mirador` is on PATH);
   - clone: `git clone <Repo>` into a sensible local dir, then work inside it;
   - `mirador open <Artifact>` → the CLI prints the **handoff packet**;
   - reframe it through your own brain into the one-screen brief (next section),
     then leave the user in a **refine** session (`mirador refine <Artifact>`).
3. **Lighter rungs if the user prefers.** T0 read: just open the `Read-only:` URL
   (WebFetch it to brief them; no clone). T1 comment (no CLI): help them compose an
   `@mirador-response` block to paste back — the owner ingests it via `mirador inbox`.
4. **The loop grows by doing its job.** Once onboarded, the user can `mirador share
   <slug> --with <email>` onward to the lenses *they* need. Convergence is distribution.

## Workflow on open / pull — the handoff

`mirador open <slug>` (and a pull that brings collaborators' refinements) prints a
**handoff packet**: changed sections + the intent notes behind them + a pointer to
your brain source. Git gives a diff; the handoff is the product on top of it.

**You write the brief — by reframing the packet through your own memory:**

1. Read your own brain (your memory + `CLAUDE.md`/`AGENTS.md`).
2. One-screen brief: *what changed* → **why it matters to this user** (their lens)
   → how it moves toward/away from the artifact's **vision**.
3. Cite the intent notes (the writer's reasons); don't restate the raw diff.
4. End in **2–3 concrete next-refinements** — imperatives, not a question.
5. Tabular / single-critical-item. No AI-prose, no preamble.

Two readers with different brains get **visibly different briefs** — that
difference, *because of the brain*, is the point. Manual mode: `mirador handoff
<slug>` emits the same packet for a human with no agent.

## Refine loop (inside a mirador artifact)

The artifact is a markdown++ `source.md` — wet clay, not a finished page. The
recipient's verb is **refine**, not read.

1. **Refine freeform.** The user talks to you; you edit `source.md` with your
   normal tools. Edit by *section* — headings carry stable `{#anchor}`s, so touch
   only the sections you mean to. `mirador preview <slug>` renders the view.
2. **On push, auto-draft the intent note.** When the user is ready, draft a
   one-line *what changed and why, in their context* — never make them write it.
   Silently infer the collaboration move (critique / extend / tighten / reframe /
   question / endorse) — **never name it to the user** — and run:
   `mirador push <slug> --intent "<one line>" --move <inferred>`
3. The CLI writes the intent note + a structured diff the next reader's agent will
   reframe through *their* brain. The move is invisible scaffolding; never show it.

Never block on a form. The intent note is auto-drafted and editable, not required
input from the user.

## Workflow on a request paste

1. Parse the seed.
2. Read the brain for `author` role context.
3. Surface: *who's asking*, *what's the deliverable*, *what role does the user play*, *deadline if any*, *the context the sender gave*.
4. Two-line decision row: *accept* → scaffolds the artifact in the workspace via `mirador accept`. *decline* → sends a polite no via `mirador decline --reason "<text>"`.

## What this skill does NOT do

- **Does not re-implement the CLI.** Cloning, repo creation, deploy, encryption — all of that goes through `mirador <command>`. The skill orchestrates and briefs; the CLI does. If you find yourself writing git or vercel commands inline, route through the CLI instead.
- **Does not invent metrics or quote the sender's note loosely.** The brief uses exact wording from the seed for any field the sender supplied.
- **Does not list options before loading the artifact.** See § Activation contract.
- **Does not personify itself with AI-slop language.** No "I'm here to help", no "Let me assist". The skill is a function; it reports findings, not feelings.

## Voice

Confident with a wink. English. No filler, no fake enthusiasm, no decorative
emoji. Full voice spec at [`docs/design/voice.md`](../../docs/design/voice.md).

Canonical samples:

- "Daniel sent you q2-report."
- "Copied. Paste it in."
- "Locked."
- "Ready. Try `mirador new <slug>`."

## What mirador is not

- Not a SaaS — the user owns the repos and the Vercel deploy.
- Not a chat app — the seed is the message; the agent is the runtime.
- Not a Notion-AI rival — git is the substrate; this is collaboration on top.

## Source of truth

- Design + decisions: [`docs/design/spec.md`](../../docs/design/spec.md)
- Implementation spec: [`docs/superpowers/specs/2026-05-21-mirador-v2-design.md`](../../docs/superpowers/specs/2026-05-21-mirador-v2-design.md)
- CLI: `mirador --help`