pi-agent-dashboard

Ship an OpenSpec change after openspec-apply completes. When only QA/manual tasks remain, marks them done (tested later), archives + syncs specs, commits, pushes, opens a PR against develop, watches CI, waits for CodeRabbit, auto-applies safe fixes and re-pushes, loops until CI green + no actionable review threads, then squash-merges with branch delete and removes the worktree. Use after implementation is done and the change is ready to land. Triggers: "ship this change", "ship it", "land the change", "merge and clean up", "post-apply ship".

Worktree-side implementation orchestrator for an OpenSpec change. Idempotent: gates automated scenarios on filesystem reality (test file exists + passes in the docker harness), not the tasks.md checkbox. Owns the red-test fix loop (never re-invokes apply on a checked task), runs the docker harness on its auto-derived port with always-teardown, then drives ship-change INLINE with a manifest-aware defer. Boundary-reverse escape hatch writes SHIP_IT_BLOCKED.md. Runnable headless. Triggers: "ship it", "build and ship this change", "run ship-it", "implement + test + land in the worktree".

Switch a monorepo extension/skill package between its published npm source and its local working-tree source, guaranteeing exactly one source per package. Use when "my edits don't take effect", "load local extension", "test the published npm build", or reconciling dev vs distribution package sources.

Generate and edit images using Google Gemini image models via the nano-banana CLI. Use when the user asks to create, generate, make, or edit images with AI. Supports text-to-image, image editing, style transfer, and multi-image composition. Trigger on requests like "create an image", "generate a picture", "make me a logo", "edit this photo", "add X to this image".

Render a scripted video project into mp4 clips with the Google Veo 3.1 API. Reads a project's shot package (the shots/*.md format produced by the veo-showreel-production-kit) and generates one clip per camera cut — reusing the Full Veo prompt, negative prompt, seed, aspect/resolution, world-anchor reference and first-frame storyboard sketch already written in each shot file. Backed by the `pi-veo` CLI (a TypeScript port — no Python). API key is configurable per project via a .env. Use when: "render the Veo video for <project>", "generate the videos from the shot scripts", "make the clips with Veo", "re-render shot 03B".

Turn a video timeline + voiceover into a reproducible, sliceable Veo 3.1 prompt package with a consistency anchor and AI storyboard sketches.

Offline-mine this project's pi session JSONL logs into reusable, verified knowledge. Walks sessions newer than a watermark, extracts five signal classes (faults, ask_user decisions, corrections, procedures, docs) anchored on objective outcomes, promotes only patterns recurring across >= N sessions, and routes distilled artifacts into existing sinks (skill_manage, memory, docs + ctx_index). Use when the user says "mine my sessions", "distill session knowledge", "what have I learned across sessions", "extract lessons from logs", or "turn my pi history into skills/memory".

Cut a new pi-agent-dashboard release. Promotes `## [Unreleased]` in CHANGELOG.md to a versioned section, bumps all workspace package.json versions per SemVer, commits, tags `v<version>`, and pushes — which triggers the Release workflow that publishes **10 npm packages** (root + shared/extension/server/web/image-fit/kb/kb-extension + session-distiller/distill-session-knowledge via `npm publish -ws --include-workspace-root`) and the Electron artifacts and creates a GitHub Release (published automatically for production tags `vX.Y.Z`; draft for pre-release tags `vX.Y.Z-rc.N`). Use when the user says "cut a release", "release vX.Y.Z", "publish a new version", "tag a release".

Draft real-life test SCENARIOS (not smoke tests) from a change/feature spec (OpenSpec optional). Derives edge-case, performance, frontend-quirk, and error-handling scenarios using ISTQB design techniques, routes each to your project's test levels, and writes a standalone test-plan.md catalog. When a scenario's (input · trigger · observable) triple cannot be filled from the spec, the spec has a gap — the skill emits decision-forcing clarification questions and (in proposal/design stage) STOPS to ask. Use when the user says "design test scenarios", "what should we test for this change", "the tasks are just smoke tests", "build a test plan", "find edge cases", "is this spec testable", or before writing the ## Tests / ## Validate sections of a tasks.md.

In-flight adversarial check on a non-trivial decision BEFORE it stands — distinct from post-hoc code review of a finished diff. Use on triggers like "stress-test this decision", "are we sure about this", "verify before commit", "poke holes in this", when working in unfamiliar code, or when an irreversible/high-stakes step (migration, prod deploy, public API) is about to be taken. Does not replace the project's code-review or openspec-verify gates; it runs earlier, while course-correction is cheap.

Develop-side planning orchestrator for an OpenSpec change. Chains artifact creation (openspec-new-change/-ff/-continue) → doubt-driven-review of proposal.md + design.md → scenario-design → category-routed fold of automated scenarios into tasks.md, then STOPS at the git-worktree boundary for the human checkpoint. Main interactive session only; never a subagent. Triggers: "plan this change", "draft the proposal and plan", "scaffold + review + fold", "prep a change for building".

Diagnose problems in the running pi-agent-dashboard system. Tail ~/.pi/dashboard/server.log, probe /api/health for mode + uptime, check bridge WebSocket connectivity, triage vitest failures via tee→grep, inspect known-issue FAQ entries (Electron Node bin selection, Fastify + bad-Node crashes, stale-port hangs, single-instance lock). Routes UI/visual issues to the browser skill. Use when the server seems hung, a pi session won't connect, tests fail mysteriously, the dashboard shows a blank page, restart loops, port conflicts, or any "why isn't X working" / "the dashboard is doing Y" question.

Diagnose/fix worktrees missing the generated openspec-* (opsx) skills after worktreeInit. Root cause: bare `npx openspec` can resolve a squatted registry stub instead of the real CLI.

Dashboard-specific adapter on top of the generic frontend-mockup-loop skill/package. Binds the 7-step design loop to pi-agent-dashboard reality: real component sources, theme-system tokens (4 themes), isolated verification for safe preview/promote, and openspec mockup paths. Use when designing/redesigning any pi-agent-dashboard client surface. Triggers: "design a dashboard screen", "mockup a dashboard surface", "redesign SessionCard", "make dashboard UI consistent".

Run before scaffolding any OpenSpec proposal in pi-agent-dashboard to catch duplicates of archived work and contradictions with already-shipped architecture. Always run when about to create openspec/changes/&lt;name&gt;/ (proposal.md/design.md/tasks.md), especially for proposals touching tool-renderers, plugin slots, MCP rendering, or any subsystem with a recent archive entry. Skipping this check produces stale proposals that duplicate archived work and contradict shipped architecture. Triggers: 'scaffold OpenSpec', 'write a proposal', 'create change', 'openspec change new'.

Run Playwright E2E (tests/e2e/) against the docker/ all-in-one harness so it reflects LOCAL code changes, not a stale cached image.

Diagnose why pi-flows, the Anthropic-messages bridge, model resolution, a pi install, a peer, a plugin/bridge, or a build/reload is broken in the pi-agent-dashboard. Derives every fact live (works with the server down), reports pi across ALL install locations, detects peer name-skew, and routes each failure to the topology-correct fix. Use on "flow won't show", "bridge waiting_peers", "pi version mismatch", "I built it but it's still broken", "which pi is this using", "agent model fails at spawn", "diagnose the dashboard", "doctor".

Monitor and control the pi-dashboard server. List sessions, send prompts, abort runs, spawn new sessions, manage git branches, control flows, and configure the dashboard — all via REST API. Use when you need to interact with other pi sessions, check dashboard health, or orchestrate multi-session workflows.

See runtime state a console.log cannot reach — set real breakpoints, step, and dump the scope chain of a paused Node/TypeScript process. Use on triggers like "set a breakpoint", "inspect runtime state", "console.log isn't enough", "step through this", "what's in this closure at runtime", "attach a debugger". Carries a jiti launch recipe verified against this repo's TypeScript loader. Not a logging or observability-setup workflow.

Root-cause a bug already in front of you, instead of guessing at fixes. Use on triggers like "root cause this", "why is this failing", "debug systematically", "this test is flaky", "it works locally but not in CI", or when a fix attempt has already failed once. Enforces a phased evidence-first process before any code change. Not a feature-build or ship workflow.

Scaffold an unconfigured directory into a configured pi project. Interactive, profile-driven: lists project profiles (coding, docs, plus user profiles), asks which to use, previews the planned writes, and on confirmation writes AGENTS.md, .pi/settings.json (with a worktreeInit hook + toolset), and prompt files. Use when a bare directory needs turning into a working pi project, or when the dashboard's "Initialize" button spawns this session.

A mechanical, countable anti-slop checklist for AI-generated frontend. Catches the specific signatures an undirected model defaults to: AI-purple glows, Inter-everywhere, em-dashes, div-based fake screenshots, eyebrow-on-every-section, beige+brass "premium" palettes, generic Jane Doe / Acme data. Advisory layer that pairs with frontend-mockup-loop (which owns the cite-a-source loop plus WCAG gates) but works standalone in any React/Tailwind/HTML project. Triggers: "does this look AI-generated", "anti-slop pass", "remove the AI tells", "why does this look templated", "design review for slop".

Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.

Plan, build, and iterate UX-friendly frontend mockups via a ground→contract→mockup→test→fix→learn loop, acting as an expert UX designer who grounds every decision in externally documented public design rules (Nielsen heuristics, Laws of UX, WCAG, GOV.UK/USWDS/Material). Uses the bundled serve_mockup, score_mockup, and init_ui_contract tools plus a ui-contract.md design control plane to keep screens consistent. Works in any React/Tailwind/shadcn (or plain HTML) project. Use when designing new screens, adapting existing UI, enforcing cross-screen consistency, or doing a UX review. Triggers: "design a screen", "mockup this UI", "wireframe", "make the UI consistent", "adapt the existing design", "improve this layout", "UX review", "is this good UX".

Create and edit pi-flows flows and agents from the main session. Use when the user wants to create a new flow, add or change an agent, or edit an existing flow/agent. Covers agent frontmatter, flow YAML, step types (agent, fork, agent-decision, code, code-decision, flow-ref), model references, the flow_agents/flow_write tools, code-handler generation, write locations, editing an existing flow vs creating one, and fixing validation errors.

Semantic HTML, keyboard navigation, focus states, ARIA labels, skip links, and WCAG contrast requirements. Use when ensuring accessibility compliance, implementing keyboard navigation, or adding screen reader support.

Diagnose failed GitHub Actions runs for pi-agent-dashboard. Maps the 6-workflow taxonomy (ci.yml, ci-electron.yml, _electron-build.yml, publish.yml, sync-release-version.yml, deploy-site.yml), walks the release pipeline (prepare→publish→electron→github-release with strict needs[] contract), surfaces known failure modes (lockfile mismatch, bad Node version, CHANGELOG already-versioned, npm publish ordering, no-bash-on-Windows lint, missing node-pty prebuilds, GO/NO-GO bundle-server guard), and shows how to read `gh run` logs and retrigger failed jobs. Use when a CI run is red, a release is stuck, a workflow won't dispatch, or you need to understand which workflow does what. For triggering a release see `release-cut`; for revoking one see `release-revoke`.

Drive static-analysis code quality in pi-agent-dashboard with Biome (analyze → fix → test). Two modes — changed-files (the goal-loop daily driver, scoped to git diff vs develop) and whole-repo (explicit, scoped cleanup). Owns the procedure; the goal-plugin's judge owns when-to-stop via the `quality:changed` exit code. Use when asked to "improve code quality", "lint and fix", "clean up warnings", "fix Biome issues", "run static analysis", or when setting a code-quality goal. Skip for one-line edits.

Reusable component patterns for cards, sections, forms, and layouts with consistent prop interfaces and composition strategies. Use when creating new components, refactoring existing ones, or establishing component design patterns.

Create and edit pi-flows flows and agents from the main session. Use when the user wants to create a new flow, add or change an agent, or edit an existing flow/agent. Covers agent frontmatter, flow YAML, step types, model references, the flow_agents and flow_write tools, write locations, and how to fix validation errors.

Mine docs/faq.md from README.md and docs/*.md. Dispatches haiku subagents per source doc to extract recurring how-to / what-is questions, dedupes against existing FAQ, and merges entries in caveman style. Use when the user asks to "build / regenerate / extend the FAQ", "mine docs into FAQ", "create FAQ from README + docs", or "process knowledge into faq.md".

Disciplined implementation in pi-agent-dashboard. Pairs (a) the 3-component rebuild matrix — extension→reload, server→restart, client→build+restart, openspec-apply→full rebuild — with (b) the project's code discipline rules (TDD, simplicity-first, surgical changes). Use when starting to write code, after editing src/extension|src/server|src/client, when unsure what to rebuild after a change, or before committing. Loads on triggers like "I changed the bridge", "rebuild and restart", "implement X", "after edit", "TDD this", "how do I land this change". Skip for trivial edits.

Generate and edit images using Google Gemini image models via the nano-banana CLI. Use when the user asks to create, generate, make, or edit images with AI. Supports text-to-image, image editing, style transfer, and multi-image composition. Trigger on requests like "create an image", "generate a picture", "make me a logo", "edit this photo", "add X to this image".

Revoke or rollback a pi-agent-dashboard release. Deletes the GitHub Release (draft or published), removes the git tag locally and on origin, deprecates the npm package version (since `npm unpublish` is blocked after 72h / for packages with dependents), and optionally reverts the `chore(release): vX.Y.Z` commit. Use when the user says "revoke release", "rollback release", "delete release", "unpublish vX.Y.Z", "yank release".

Mobile-first responsive patterns with sticky headers, floating CTAs, accessible navigation, and touch-friendly interactions. Use when implementing responsive layouts, mobile navigation, or ensuring touch-friendly UI.

Tailwind CSS utility patterns with shadcn/ui component usage, theming via CSS variables, and responsive design. Use when styling components, installing shadcn components, implementing dark mode, or creating consistent design systems.

CSS custom properties theme architecture for 4 themes (studio, earth, athlete, gradient) with data-theme attribute switching and theme-aware components. Use when implementing theme switching, defining color schemes, or creating theme-responsive UI elements.

TypeScript strict mode patterns with interfaces, type guards, generics, and utility types. Use when defining types, creating type-safe functions, handling nullable values, or implementing generic components.

Form validation combining Zod schemas with React Hook Form, including localized error messages, Server Action integration, and shadcn/ui Form components. Use when building forms, validating user input, handling form submissions, or implementing Server Actions with validation.

Transcribe video and audio files to SRT subtitle format with speaker diarization using the Soniox API. Use when the user wants to transcribe meeting recordings, videos, or audio files. Supports MKV, MP4, MOV, M4A, and MP3 files. Triggers on "/transcribe", "transcribe my meetings", "transcribe videos in ~/Movies", "create subtitles for recordings", or any request to convert audio/video to text.