Project agent memory

This file is the project's committed home for project-intrinsic agent knowledge: build, test, release, architecture, and sharp-edge notes that should travel with the code.

What this repo is

A published agent skill (skills/superdesign/) that drives the SuperDesign design canvas via its CLI. The skill is prose, not code - there is no build/test suite. Files:

• skills/superdesign/SKILL.md - entry point (front-matter + core workflow)
• skills/superdesign/references/SUPERDESIGN.md - main design workflow (always read) + COMMAND CONTRACT
• skills/superdesign/references/INIT.md - repo-analysis (init) instructions
• skills/superdesign/references/RESUME.md - durable UI context + warm cross-session iteration path
• skills/superdesign/references/GRAPHIC.md - poster/marketing-asset workflow (loaded only for graphics)
• skills/superdesign/references/PRESENTATION.md - outline approval, presentation generation, assets, and slide-safe iteration
• skills/superdesign/references/WEBSITE.md - live-site extraction recipes (loaded only for reference-URL tasks)
• skills/superdesign/references/COMPONENTS.md - Petite-Vue template spec (loaded only before create/update-component conversions)
• skills/superdesign/references/design-with-your-model.md - caller-model HTML authoring/import path (loaded only when explicitly requested or after create/iterate retry failure)
• skills/superdesign/{SUPERDESIGN,INIT}.md - deprecated compatibility forwarders (do not add content)

Skill flow invariant: two entry paths

SKILL.md branches on Step 1 into a real-codebase path (repo init is mandatory) and a no-codebase path (empty/scratch/sandbox workspace with no frontend code - skip init, gather design context conversationally, design via SUPERDESIGN.md "SOP: BRAND NEW PROJECT"). Before cold discovery, every real-codebase UI request checks .superdesign/resume.json; valid state for the same target follows RESUME.md regardless of request wording, reuses the saved bundle without rereading init/source context, and reads or adds only narrowly relevant source when targeted context expansion is required. Within the cold real-codebase path, SUPERDESIGN.md's UI TARGET ROUTING further splits by target: an existing rendered page goes reproduce-first (Step 3a ground truth), while a new page in the codebase skips reproduction entirely ("SOP: NEW TARGET IN EXISTING CODEBASE") - keep reproduction rules scoped to existing rendered targets. Any init/hard-gate rule you edit must stay scoped to the real-codebase path so it does not block the no-codebase path (see the HARD GATE and MANDATORY INIT rules in SUPERDESIGN.md). A separate Step 0 preflight halts when shell execution is unavailable (e.g. ChatGPT Chat mode) - distinct from the auth/login path, where the CLI actually ran.

Ground truth for CLI behavior

The skill invokes npx --yes @superdesign/cli@latest. When editing any command example or the COMMAND CONTRACT, verify against the published CLI - do not trust memory. @beta is what @latest becomes, so use it to check upcoming surface:

• npx --yes @superdesign/cli@beta <command> --help for flags
• The bare command (no args) is the preflight surface: version, auth: status line (works logged-out too), recent projects
• Live-run read-only commands (search-prompts, get-prompts, list-design-systems) to see real output
• Valid --model values: run list-models (or pass a bogus --model to any generation command; the validation error prints the same list)
• Default (no --json) output is agent-optimized (compact TOON + help[] hints); add --json only for the full machine payload, --full only to expand truncated fields

Plugin packaging & release

The repo root doubles as four plugins off one skills/superdesign/ tree: .codex-plugin/plugin.json (Codex), .claude-plugin/plugin.json (Claude Code, alongside a self-hosted .claude-plugin/marketplace.json that lists the repo root as "source": "./"), .cursor-plugin/plugin.json (Cursor marketplace, with a matching .cursor-plugin/marketplace.json in the same repo-root-as-source shape; Cursor listings are submitted manually to the Cursor team, see https://github.com/cursor/plugin-template), and the root package.json (DeepSeek Harness — see below). Releasing a new version is a single chore(plugin): bump to X.Y.Z commit editing the version in all four manifests plus the ## Unreleased heading in CHANGELOG.md, merged via PR - there are no git tags, no GitHub releases, and no CI/publish workflow (verify with git tag / gh release list before assuming otherwise). Both marketplaces treat an explicit version as the update cache key, so pushing commits without bumping ships nothing to users.

The DeepSeek Harness plugin is the odd one out, because dsh reads no plugin.json. It installs an npm package whose package.json declares dsh.bundle, pointing at a config layer (dsh/cordis.patch.yml) that mounts dsh/index.js as a ctx.skills provider over the same skills/superdesign/ tree (publish.md). Two constraints on that file are load-bearing. It stays plain ESM with no build step, because dsh plugin add github:... fetches sources rather than build output, and a prepare script would force every user to allowlist a build before the first install works. And it takes no dependency on @deepseek-ai/*, because an out-of-tree bundle depending on an in-box package installs a second copy that drifts from the host's; that is why it implements the list/get provider contract directly instead of reusing dsh-skill-filesystem. The skill's description is parsed out of SKILL.md at runtime rather than restated, so there is nothing to keep in sync. Discovery is the dsh-plugin GitHub topic on this repo.

Validate any manifest edit with claude plugin validate ./.claude-plugin/plugin.json --strict and claude plugin validate ./.claude-plugin/marketplace.json --strict (the bare claude plugin validate . resolves to the marketplace file, not the plugin one). The Claude Code review pipeline runs the same check on submission.

The marketplace-facing display name lives in three files. The two ChatGPT-facing ones must stay in sync with each other - .codex-plugin/plugin.json interface.displayName and skills/superdesign/agents/openai.yaml display_name - and carry the 01 listing-sort prefix. .claude-plugin/plugin.json displayName deliberately drops that prefix, since Claude Code's /plugin picker does not sort by name. All three are distinct from machine identity - the plugin slug (both plugin.json name fields), the skill dir/SKILL.md name, and the $superdesign / superdesign:superdesign invocations - which must never change on a rename.

Maintaining this file

Keep this file for knowledge useful to almost every future agent session in this project. Do not repeat what the codebase already shows; point to the authoritative file or command instead. Prefer rewriting or pruning existing entries over appending new ones. When updating this file, preserve this bar for all agents and keep entries concise.