pneuma-project
starsforks
How to install pneuma-project?
pandazki/pneuma-skills/pneuma-project
$npx -y skills add pandazki/pneuma-skills --skill pneuma-projectProject-context awareness — multi-session workflows around one topic, shared materials and preferences, and cross-mode handoffs as a high-value user path.
SKILL.md
| 1 | # You're inside a Pneuma project |
| 2 | |
| 3 | A Pneuma project is the user's **organizational unit for one ongoing topic** — think "Brand identity for a startup", "Marketing site for a product launch", "Pitch package for a Series A". Inside one project, the user runs **multiple sessions in different modes** that all contribute to the same goal: a session in `illustrate` produces brand visuals, a session in `webcraft` builds the marketing site, a session in `slide` writes the pitch deck. They share materials, share preferences, and can hand off context to each other. |
| 4 | |
| 5 | You are one of those sessions. The work you do here is part of a larger arc, not a standalone exercise. Approach the conversation with that in mind. |
| 6 | |
| 7 | ## Where you live, where the project lives |
| 8 | |
| 9 | Two paths matter, both injected as env vars: |
| 10 | |
| 11 | - `$PNEUMA_PROJECT_ROOT` — the user's project directory. **Final deliverables go here.** Websites, decks, videos, docs the user will actually use — they all land in this directory or its subfolders. |
| 12 | - `$PNEUMA_SESSION_DIR` — your private working area, also your CWD. Drafts, scratch notes, internal state, intermediate artifacts. **Don't write deliverables here.** |
| 13 | |
| 14 | Project metadata lives at `$PNEUMA_PROJECT_ROOT/.pneuma/project.json`. Read it for project identity and description. Don't edit it casually — that's the project's identity, the user manages it. |
| 15 | |
| 16 | ## Project meta — what the launcher / project chip read |
| 17 | |
| 18 | The project's user-visible identity (name, description, icon) lives in two recognized files under `$PNEUMA_PROJECT_ROOT/.pneuma/`. Treat these as the **only** project-meta surface — the launcher and the in-app project chip read exactly these paths and nothing else, so guesses like `icon.png`, `cover.svg`, or `meta.json` will silently do nothing. |
| 19 | |
| 20 | ### `project.json` — manifest |
| 21 | |
| 22 | Schema: |
| 23 | |
| 24 | ```json |
| 25 | { |
| 26 | "version": 1, |
| 27 | "name": "pneuma-demo-project", |
| 28 | "displayName": "Pneuma Demo Project", |
| 29 | "description": "...optional, shown under the title in the project chip and launcher card...", |
| 30 | "createdAt": 1740000000000 |
| 31 | } |
| 32 | ``` |
| 33 | |
| 34 | - `name` is the directory-derived slug. Don't change it. |
| 35 | - `displayName` and `description` are user-facing; you may refine them when the user explicitly asks ("update the project description to X"). Otherwise leave them alone. |
| 36 | - `version` and `createdAt` are runtime fields. Don't touch. |
| 37 | - The launcher hot-reloads this file via chokidar — saving the JSON updates the UI within ~1s, no restart needed. |
| 38 | |
| 39 | ### `cover.png` — project icon |
| 40 | |
| 41 | Strict rules: |
| 42 | |
| 43 | - **Exact path:** `$PNEUMA_PROJECT_ROOT/.pneuma/cover.png`. Anything else (`icon.png`, `cover.jpg`, `cover.svg`, `cover@2x.png`, or a copy at the project root) is **not** recognized — the launcher falls back to a generated dotted-letter cover. |
| 44 | - **PNG only.** No JPEG / SVG / WebP fallback exists. |
| 45 | - **Square is best.** Rendered inside a square frame with `object-fit: cover`, so non-square inputs get cropped on the longer axis. Generate at 512×512 or larger; the runtime resizes for display. |
| 46 | - **Hot-reload.** The server watches `.pneuma/` and re-serves the cover with mtime-based caching, so overwriting the file shows up in the UI within a second. The cover lives outside any session's shadow git, so iterating is a plain file overwrite — there's no per-turn checkpoint to revert through. |
| 47 | - Don't write to `$PNEUMA_PROJECT_ROOT/.pneuma/sessions/<your-id>/thumbnail.png` thinking it's the project icon — that's the **per-session viewer thumbnail**, scoped to your own session, not the project. |
| 48 | |
| 49 | If the user asks you to "make a project icon / cover / logo" and you produce an image (typically inside `illustrate`, `draw`, `kami`, or another image-producing mode), save the final asset to `$PNEUMA_PROJECT_ROOT/.pneuma/cover.png` and confirm the path back to the user. Don't drop it in your session dir — that won't be picked up. |
| 50 | |
| 51 | ## The Project Atlas — your canonical briefing |
| 52 | |
| 53 | If your CLAUDE.md contains a `<!-- pneuma:project-atlas:start --> ... <!-- pneuma:project-atlas:end -->` block, the project has been atlas-seeded. The block is a **pointer**, not the briefing itself — the runtime keeps your prompt lean by not inlining the atlas file every turn. |
| 54 | |
| 55 | **On session start (or your first action of substance), Read** `$PNEUMA_PROJECT_ROOT/.pneuma/project-atlas.md`. Treat its contents as authoritative for: |
| 56 | |
| 57 | - What this project is, who its audience is, what's in scope |
| 58 | - Project-wide conventions, file structures, naming rules |
| 59 | - Locked-in design / technical decisions ("anchors") |
| 60 | - Open threads the user has flagged |
| 61 | |
| 62 | **Use the atlas before re-asking the user.** If it already states the brand color or the deliverable directory, don't ask — just use it. |
| 63 | |
| 64 | You don't need to re-Read the atlas every turn — once is enough for a session unless the user signals it changed (e.g. "I just refreshed the atlas"). I |
People who liked this also viewed
6 picksType
- hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026
- request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026
- explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026
- ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
