Create Mode

Create Mode

A guided journey for adding a new mode to Pneuma Skills. The journey has three phases — Discovery (ask the right questions), Brief (write down key choices and resolve material unknowns), Implementation (generate files). Each phase has a clear handoff to the next; never skip Brief. Pneuma has a stable contract layer; a concise design brief keeps the viewer aligned with the user's intended work.

This skill runs in Claude Code and Codex. Use the active harness's file, planning, browser, and question tools; native Claude tool names are not prerequisites. Resolve paths from this skill directory.

Apply the root product and architecture guidance and Engineering Judgment to the brief: identify domain invariants and ownership before choosing Source kinds or actions, and inspect existing modes and mature implementations before building anew.

The reference material in references/ is where the knowledge lives — go read the relevant one whenever you're about to make a meaningful decision. SKILL.md is the journey, not the textbook.

When to use

Trigger this skill when the user asks for any of:

• "create a new mode for X"
• "fork slide / webcraft / … for a different domain"
• "scaffold a mode"
• "add a [mindmap | spreadsheet | timeline | annotator | …] mode"
• "design the viewer for a mode that …"

If the user only asks about an existing mode's behavior, this skill is not the right tool — direct them to docs/reference/viewer-agent-protocol.md or the mode's own SKILL.md.

Phase 1 — Discovery interview

Goal: fill the design brief from the user's request, existing decisions, and repository evidence. Ask only for missing choices that materially affect the result. Use the question tool available in the active harness, or a concise chat question; never require a tool named AskUserQuestion. Bundle closely related unknowns and continue independent work while waiting.

Discovery checklist (reuse known answers; ask only where needed)

1. Identity — name (kebab-case), one-line displayName, two-line description, intended icon style. This is the only question you can pose as a single multi-line form.
2. Domain in one sentence — what is the user creating with this mode? A document? A canvas of objects? A timeline? Let the user answer free-form before you offer Source-kind options. Read references/domain-and-sources.md while they think.
3. Inspiration vs original — does this mode borrow content (commands, references, design language, taxonomy) from an existing tool, library, or project? If yes, ask the upstream's name + URL + license. This determines whether you'll write NOTICE.md and set inspiredBy. Read references/external-integrations.md for the borrow-vs-inspiration line.
4. Source kind (branch on Q2 + Q3) — present file-glob / json-file / aggregate-file / memory with the one that fits Q2's domain pre-selected as "Recommended". Explain why it fits in the option's description. If aggregate-file wins, note that you'll also generate domain.ts.
5. Workspace model (when Q4 is not memory) — "all" / "manifest" / "single"; do users author many independent files, an ordered/structured set, or one main document? See references/viewer-contract-patterns.md for the FileWorkspaceModel matrix.
6. ViewerAddress vocabulary — "what's the smallest thing the user can point at?" Propose a draft { contentSet?, ... } based on Q2's domain noun (slide / page / row / node / heading). Confirm with the user; explicitly name the coarse "where" key and any fine "within" key. See references/viewer-contract-patterns.md::ViewerAddress.
7. Initial action space — propose the smallest sufficient set with id / label / category / agentInvocable, tying each action to a concrete task. Include navigate-to when users need addressable navigation; add ui and custom for demonstrated needs. Don't list capture — it's framework-built-in.
8. External integrations (conditional — only ask if Q2 or Q3 implied an external API / SDK / CDN / library / API key) — does the viewer fetch external APIs (→ proxy)? does the agent or viewer need API keys (→ init.params with sensitive: true + envMapping)? does this need an MCP server (→ skill.mcpServers)? Read references/external-integrations.md for the proxy / Babel-JIT / NOTICE patterns.
9. Cloud surfaces — resolve both choices in every brief; reuse existing decisions and ask only when unclear. Two independent questions, in this order: (a) should a finished piece of work in this mode be shareable as a read-only page a stranger can open with no Pneuma installed? — that's the hosted player, and it obligates the viewer to render from workspace files alone, with no live backend; (b) does the mode produce a deployable static site? — that's Vercel / Cloudflare Pages deploy. Put the real trade-off in each option's description: "yes" buys shareability and costs a read-only degradation path plus a browser verification pass on every viewer change; "no" costs nothing and can be revisited in a later release. Read references/cloud-surfaces.md before you ask — the compatibility checklist there is what "yes" actually commits to.
10. Seed strategy — single file, multiple use-case content sets, or language×theme matrix? What's the first seed's narrative — what story does it tell to a brand-new user? See references/seed-and-showcase.md.
11. Evolution directive — give the evolve agent a one-sentence "what should it learn for this mode?" (e.g., "Learn the user's slide design preferences: typography, palette, density, structure"). This is what makes the mode personalize over time.

What to read while interviewing

If you ever find yourself stuck choosing between two patterns, open references/case-studies.md — it indexes which existing mode made which choice, so you can read that mode's manifest as a concrete precedent.

Phase 2 — Design brief & user confirmation

Goal: write down every key choice with a one-line rationale in one place. Use the brief for Phase 3; label assumptions and resolve material unknowns before dependent implementation. An approved brief or explicit instruction to implement already supplies authorization.

Brief structure

Present a concise brief in chat, or link the design document if the task already uses one. Cover the applicable fields below without asking the user to repeat known decisions:

# Mode design brief — <displayName>

## Identity
- name: <kebab-case>
- displayName: <string or LocalizedString>
- description: <one sentence>
- icon: <SVG approach: e.g. "lucide-style line icon, single path">

## Domain
<one paragraph — what the user is creating; what the viewer renders; what the agent does>

## Invariants and implementation choice
- required invariants: <what must remain true, and how it will be verified>
- state and writers: <persistent work, transient UI state, and who may change each>
- reuse: <existing mode / project implementation / library, or the concrete gap>
- added abstraction or complexity: <its contract or real variation and benefit; omit if none>

## Source layer
- kind: <file-glob | json-file | aggregate-file | memory>
- domain type T: <the TypeScript type the viewer subscribes to, sketched>
- why this kind: <one sentence — see references/domain-and-sources.md>
- domain.ts needed: <yes | no>

## Workspace model
- type: <"all" | "manifest" | "single">
- multiFile: <true | false>
- ordered: <true | false>
- hasActiveFile: <true | false>
- supportsContentSets: <true | false>

## ViewerAddress vocabulary
- coarse keys: <e.g. `contentSet?`, `slide`>
- fine keys: <e.g. `selector?`, `anchor?`>
- example address: `{ contentSet: "en-light", slide: 3 }`
- documented in: skill/SKILL.md (will write a sub-section)

## Action space
| id | label | category | agentInvocable | params |
|----|-------|----------|----------------|--------|
| navigate-to | Go to … | navigate | true | { address: object } |
| … | … | … | … | … |

(framework provides `capture` automatically — not listed)

## Seed strategy
- shape: <single | content-sets-by-use-case | language×theme>
- content sets: <list, with each name + one-line purpose>
- first seed narrative: <one sentence>

## External integrations
- proxy: <none | list routes>
- init.params: <none | list with sensitive flag>
- skill.mcpServers: <none | list>
- viewer.refreshStrategy: <"auto" | "manual">
- NOTICE.md required: <yes | no — if yes, upstream name + license + version pinned>
- inspiredBy: <none | { name, url }>
- external effects (if any): <observable completion, retry/idempotency, cancellation, and recovery or undo limits>

## Cloud surfaces
- hosted player: <yes | no — and the reason, in the vocabulary of references/cloud-surfaces.md>
- artifact deploy: <none | vercel + cf-pages>
- obligations (only when either is yes):
  - registration: <`core/player-support.ts` whitelist entry / `compatibleModes` entry in BOTH deploy plugins + an `/export/<name>` route>
  - read-only degradation: <which affordances hide when `editing === false`; which `/api/*` calls gate on the `staticPlayer` store flag>
  - verification: <build the player, load a real package for THIS mode in a browser, exercise it read-only, console clean>

## Launcher surface
- visibility: <public (in gallery) | hidden (internal-only, manifest.hidden=true)>
- featured-eligible: <yes (default; showcase highlights present) | no (no showcase or hidden mode)>

## Evolution directive
> <one sentence to the evolve agent>

## Open questions / deferred
- <anything we punted on; e.g. "showcase imagery defers to /showcase">

Before implementation

If the user has authorized implementation and the brief fits that scope, proceed. Ask only when a material unresolved choice would change the product or exceed the agreed scope. Keep the brief current as the user steers; do not request approval again for decisions already made.

Phase 3 — Implementation

Once the brief is sufficiently resolved and implementation is authorized, generate files in this order. Use templates from assets/templates/; replace the TODO: placeholders against the brief. Don't ad-lib structure — the templates encode the conventions extracted from existing modes.

Step 1 — Scaffold the directory

modes/<name>/
├── manifest.ts          ← from assets/templates/manifest.ts.template
├── pneuma-mode.ts       ← from assets/templates/pneuma-mode.ts.template
├── domain.ts            ← only if Source kind is aggregate-file; from domain.ts.template
├── skill/
│   └── SKILL.md         ← from assets/templates/SKILL.md.template
├── seed/
│   └── <content sets per brief>
├── viewer/
│   └── <ModeName>Preview.tsx   ← scaffold a stub PreviewComponent
└── showcase/
    └── showcase.json    ← from assets/templates/showcase.json.template (with concept descriptions)

NOTICE.md                ← only if brief said "NOTICE.md required: yes"; from NOTICE.md.template

Step 2 — Wire up file-by-file

For each file, fill in templates against the brief. Specifics:

• manifest.ts — every brief field maps to a manifest field. The template has marked sections (// TODO: identity, // TODO: sources, etc.) — fill each from the brief. Don't add fields the brief doesn't have; brevity over completeness for v0.1.0.
• pneuma-mode.ts — the ModeDefinition binding: import manifest, wire it to a stub ViewerContract that imports the PreviewComponent and implements extractContext, workspace.resolveItems, workspace.createEmpty. See references/viewer-contract-patterns.md::pneuma-mode.ts for the binding pattern.
• domain.ts (aggregate-file only) — write the load(files) → T | null and save(value, current) → { writes, deletes } pair as pure functions. Read existing modes' domain.ts for the pattern (slide / illustrate / kami use this).
• skill/SKILL.md — follow references/skill-md-patterns.md: Scene → Viewer Contract → Core Rules → Workflow → Commands → References. Include a ## ViewerAddress vocabulary sub-section that names every key from the brief and a one-line meaning per key.
• viewer/<Name>Preview.tsx — stub. Renders a placeholder ("Mode initialized — start authoring"). Imports the Source from props.sources via useSource. The user (or you in a follow-up) will flesh this out.
• seed/ — write the first content set's files per the brief's narrative.
• showcase/showcase.json — from template, with brief's tagline + 3 highlight concept descriptions. Images are generated in Step 4.
• NOTICE.md (if required) — pin upstream name + URL + license + version + sync date; include the "what we borrowed / what we adapted / what we dropped" mapping table. Template at assets/templates/NOTICE.md.template.

Step 3 — Register the mode and its supported surfaces

Complete frontend registration (3a), launcher discovery (3b), and public documentation (3c) as applicable. These serve different consumers: a mode can launch successfully while remaining absent from the gallery or docs.

Use the visibility decision recorded in the brief. Public modes need all three; hidden modes still need frontend registration but stay out of public catalogs and may omit the gallery entry as described below. Resolve visibility only if it is still unknown. Cloud registration (3d) is conditional on the brief's ## Cloud surfaces decision and the verification pass described there.

3a. Frontend dynamic-import registry — core/mode-loader.ts

Add an entry to the builtinModes: Record<string, ModeSource> map so the frontend can dynamic-import the mode's manifest and viewer. Without this, the mode 404s when a user opens its URL ("Unknown mode: <name>").

// core/mode-loader.ts — inside `const builtinModes: Record<string, ModeSource> = { ... }`
<name>: {
  type: "builtin",
  manifestLoader: () =>
    import("../modes/<name>/manifest.js").then((m) => m.default),
  definitionLoader: () =>
    import("../modes/<name>/pneuma-mode.js").then((m) => m.default),
},

Copy the shape from the neighboring entry rather than from memory — the field names are manifestLoader / definitionLoader, and the type: "builtin" discriminant is required.

3b. Launcher gallery registry — server/index.ts

Add the mode's name to the builtinNames array (search for const builtinNames = [...]). This array drives /api/registry, which the launcher's marketplace UI and ProjectPanel's mode-tile grid both consume. Skipping this is the #1 way a freshly-built mode silently fails to appear in the launcher gallery even though bun run dev <name> works fine.

// server/index.ts — search for "const builtinNames"
const builtinNames = [..., "<name>"];

The launcher filters out modes whose manifest declares hidden: true, so listing a hidden mode here is harmless — the filter is the safety net. Current practice omits them anyway, so a hidden mode needs no entry; add one only if you want the filter, rather than your memory, to be what keeps it out of the gallery.

3c. Docs — public mode catalogs

If the mode is not hidden, add its row to the "Built-in Modes" table and update CLI usage in both README.md and README.zh.md. Hidden modes stay out of the public catalog. AGENTS.md links to the catalog; it does not maintain another mode list. CLAUDE.md remains the one-line @AGENTS.md import: never add content to it or copy it over AGENTS.md.