sculptor

Build or modify a Sculptor extension — a runtime ESM module loaded into the Sculptor UI. Use when asked to write an extension (or "plugin") for Sculptor, add a panel, overlay, workspace widget, home view, or settings UI to Sculptor, or to iterate on an extension with `sculpt extension`. Works from any repo; this file is a self-contained reference (the Sculptor source code is optional).

Interact with Sculptor programmatically using the sculpt CLI. Use this skill when using `sculpt`, or when designing or planning a workflow that would benefit from understanding the structural capabilities of `sculpt` (workspaces, agents, isolation, and how code flows between them).

Live, hot-reloading preview of the Sculptor WEB frontend from a phone or any browser, served through the OpenHost nginx /proxy front. ONLY relevant when running INSIDE the openhost-deployed Sculptor (the container fronted by nginx on :5050, reachable at https://sculptor.<zone>/) — NOT for local or Electron dev. Frontend-only: it reuses the single shared backend, so it previews UI/frontend changes, not a per-workspace backend. Invoke when iterating on the web UI and wanting to see it live in a browser through the OpenHost SSO front.

How this OpenHost-hosted Sculptor environment works — storage and what survives restarts, where/how to add repositories and authorize gh, and the /proxy/<port>/ capability for previewing loopback web apps from a browser. ONLY relevant when running inside an OpenHost deployment (detect via the OPENHOST_* env vars, e.g. OPENHOST_APP_NAME). Ships with the deploy image and is refreshed every release.

Test a pull request by creating a shallow clone at the PR's commit and launching Sculptor. Use when you need to test changes from a specific PR in isolation.

QA the Sculptor mobile web UI on a real iOS Simulator, driven headlessly from a Mac. A single CLI boots a notched iPhone, launches the local frontend server (parsing its port — no hardcoding), opens the app in MobileSafari, taps/swipes via idb, and screenshots each step. Includes the Add-to-Home-Screen standalone flow — the only way to verify notch / status-bar / home-indicator safe-area rendering (env(safe-area-inset-*) is 0 everywhere except real iOS). Use when visually verifying mobile/responsive changes on an iPhone.

Compare React component render counts between origin/main and the current branch during a user-defined UI scenario (e.g. panel resize, navigation). Use when verifying that performance changes actually reduced re-renders.

Deploy, verify, and reset the self-hosted Sculptor app running as an OpenHost app (built from source via openhost.Dockerfile). Covers fresh deploys, updating or switching the deployed branch while keeping data, health-checking the live instance, and a full CLI-only reset to a fresh-onboarding instance. Wraps the `oh` CLI; the app name and repo are hardcoded in the scripts and the only per-machine value (your instance host) lives in .sculptor/.env. The common flows are one-command scripts in this skill's scripts/ folder.

Launch Sculptor in a headless browser and interact with the UI via an HTTP API. Send commands via curl, get screenshots back, and visually inspect the result — like a human QA tester. Use when you need visual verification of UI changes, manual testing of features, or end-to-end testing with real Claude.

Launch the Storybook dev server and use Playwright to take screenshots of component stories. Use when you need visual verification of UI component designs or want to iterate on a component's appearance.

Update the Sculptor help docs (docs/help/ in this repo) to match a specific Sculptor release. Must be run from a Sculptor checkout on the matching release branch. Audits the markdown against that source, rewrites stale text, and recaptures/processes screenshots via the /auto-qa-changes harness. Does NOT commit or push — hands back a dirty working tree for the user to review. Inputs: - Required: Sculptor version to target, e.g. "0.27". The skill verifies the current branch is release/sculptor-v<version>.0 before proceeding.

Instructions for writing new Sculptor frontend integration tests. Covers how to use FakeClaude for deterministic agent behavior, test file setup, and the available FakeClaude commands. Use when writing new integration tests or adding tests to existing files.

Fix a bug using test-driven development.

Review a set of code changes against Sculptor's review categories and produce a markdown findings table. Use when reviewing code (your own or others').

Run Claude programmatically against collections of files in the codebase. Use for batch analysis: scrubbing sensitive data, auditing style violations, security reviews.

Bring the product specification set under docs/specs/ (SPEC.md, requirements.md, scenarios.md, scenario_coverage.md) up to date with the code that has merged to origin/main since the specs were last refreshed. Reviews the merged PRs since a recorded baseline, filters out non-product churn, and applies the needed edits to each doc — preserving its format and ID scheme — then verifies every existing claim in the docs is still true of the current code. Use periodically to keep the specs from going stale, or when asked to "update the specs" / "refresh docs/specs".

Capture Python-level diagnostics from a running Sculptor backend (`sculptor_backend`): instant thread dumps and viztracer/Perfetto traces with no special privileges, or py-spy CPU sampling / flamegraphs / native stacks against the installed signed app (one-time re-sign + sudo). Use when the backend is wedged, slow, pegging a CPU core, or deadlocked, or when you need a CPU profile or a live stack of `sculptor_backend`. Works both INSIDE Sculptor (where privileged steps are delegated to the user so the agent never kills its own backend) and from an EXTERNAL `claude`.

Hand off the current work to a fresh agent — either a new agent in the SAME workspace, or a new workspace — seeded with a summary of the current context.

Produce an architecture document from a spec, through deep codebase analysis and guided Q&A. Reads the existing spec (and mocks, if any), explores the codebase, and writes architecture.md alongside the spec. Hands off to /plan when the architecture is finalized. Input: a feature slug (or seed message from /spec with slug + paths).

Execute an implementation plan by working through each task file in order. Reads the plan's 00_overview.md, builds a TODO from the task index, then for each task re-reads implement_task.md and follows it end-to-end. The plan's final two tasks handle global test verification and spawning the Review agent. Input: a feature slug (or seed message from /plan with paths).

Create interactive HTML mocks for a feature through guided iteration with the user. Two modes: exploration (generates 3+ end-to-end variants to help the user surface ideas) and confirmation (single coherent mock to visually verify an existing design). Can be invoked standalone or from `/sculptor-workflow:spec` as input to, or output of, a spec.

Produce a detailed implementation plan from a spec and architecture document. Writes a folder of self-contained task files so the build agent can execute one task at a time without holding the full plan in context. Hands off to /build when finalized. Input: a feature slug (or seed message from /architect with paths).

Final review pass for a feature implementation. Verifies the diff satisfies the spec's requirements, that tests were written and pass, and invokes the repo's configured code-review skill. Writes review.md alongside the spec, then offers options for handling findings. Input: a feature slug (or seed message from /build with paths).

Create or update the repo's Sculptor configs (.sculptor/code.md, .sculptor/testing.md, .sculptor/docs.md). These files teach the sculptor-workflow skills how to build, run, test, and where to write docs in this specific codebase. Run this to set up a new repo, or to update the configs when your setup changes.

Write an implementation spec through guided Q&A before writing code. Scaffolds the spec file up front, clarifies the user's goals, then explores the codebase and refines through interactive Q&A so the user watches the spec evolve in the diff viewer. Offers HTML mocks at the start (or mid-Q&A) for UI-heavy features. Input: a description of the feature or change to spec out.

Propagate a branch's changes down its stacked children by merging the updated parent into each stacked branch, in order from base to tip.

Apply CLAUDE:-prefixed comments from a pull request

Stack a new workspace on top of the current branch — a handoff into a NEW workspace whose new branch is based off, and targets, the current branch.

Debug failing Sculptor frontend integration tests. Use when integration tests fail and you need to diagnose the root cause. Covers common failure modes, how to read test logs, and investigation strategies.

Guide for using design tokens in the Sculptor frontend. Use when writing or reviewing CSS/SCSS to pick correct token variables.

Run Sculptor integration tests. MUST be used whenever: - Running tests in sculptor/tests/integration/ - User asks to "run integration tests" or "run the tests" for integration test files - Using pytest on integration test files DO NOT run pytest directly for integration tests - use this skill instead. Tests must run as background processes with a Monitor watchdog.

Add a new issue type to one of Sculptor's review-rule docs. Use when you've encountered a class of bugs, anti-patterns, or flaky test patterns that should be caught in future reviews.

Summarize commits merged to origin/main as two outputs: internal release notes (categorized into Features, UI Polish, Testing, CI, Cleanup) and user-facing release notes (What's new, Improvements, Reliability). Two input modes: a Sculptor release version (e.g., "0.27") for single-release notes, or a date range (e.g., "Feb 14-23") for ad-hoc weekly notes. Defaults to the last 7 days.

Ask any question about Sculptor.