agent prompts

Most of this documentation is written for humans running the CLI. These two prompts are for coding agents — drop them into Cursor, Claude Code, Codex, or any agentic tool that can run shell commands. They tell the agent to scaffold SpecUI, then build the design system with you, step by step, validate-before-code.

Both prompts assume the agent can run npx/npm and read/write files in your repo.

---

Prompt A — Add SpecUI to an existing app

Use this when the repo already exists and you want a .specui/ contract wired in. Paste the block, change the three {{...}} placeholders, and let it run.

You are going to install SpecUI into this repository and then help me build the design system
before any more UI code ships. SpecUI is a `.specui/` folder (tokens, components, patterns,
assets, rules) plus a small CLI. The contract leads; the code follows.

Context:
- App name: {{My Product}}
- Preset: {{web-app | mobile-app | marketing-site | dashboard-data-dense | design-system-library | blank}}
- Framework: {{Next.js | Vite | React Native | …}}
- Agent tools to wire (optional): cursor | claude | codex | copilot | gemini | windsurf

Steps — do them in order, stop and confirm after each numbered step:

1. Run `npx @logicplanes/specui@latest init` with the name, preset, `--agents-md`, the right
   `--agent-tools`, and `--ci github`. Read the printed "Next steps" block.
2. Run `npx specui doctor`. Report any errors or warnings to me before continuing.
3. Open `.specui/TOKENS.yaml` and `.specui/01-brand-and-product.md`. Ask me 4–6 short questions
   about brand voice, accent color, typography, and density. Use my answers to fill them in.
4. Open `.specui/02-foundations-tokens.md`. Propose a complete token set (color, type, spacing,
   radius, shadow, motion) derived from what I told you. Wait for my approval before writing.
5. For each component my app already ships (scan src/ for buttons, inputs, dialogs, etc.):
   `npx specui add component <name> --variants <…> --states <…>`. Then fill in each
   `.specui/components/<name>/SPEC.md`, `STATES.md`, `VARIANTS.md` from the existing code.
6. Run `npx specui sync` and `npx specui validate .specui --strict`. Fix every error and
   warning it reports; re-run until it prints "SpecUI valid — no findings."
7. Open `AGENTS.md` and the rules under `.cursor/rules/` (or the tool you wired). Confirm the
   SpecUI block is there and points at the right files.
8. Summarize: what was created, what decisions were made, and what I should review next.

Rules for the rest of this project:
- Never write or modify UI code without first registering the component in `.specui/`.
- Run `specui validate .specui --strict` before considering any UI task done.
- If a token is missing, add it with `specui add token` before using it in code.
- Keep `.specui/` and the implementing code in the same commit.

---

Prompt B — Start a brand-new app with SpecUI from the first commit

Use this when you're starting fresh and want the agent to build the design system with you, step by step, before the first component is written.

We are starting a new application from scratch and the design system comes first. You will
scaffold the repo, install SpecUI as the design contract, and build tokens, components, and
patterns with me — step by step — before any UI code is written.

Context:
- App name: {{My Product}}
- Framework + tooling: {{Next.js + Tailwind | Vite + CSS modules | React Native + …}}
- Preset: {{web-app | mobile-app | marketing-site | dashboard-data-dense | design-system-library}}
- Agent tools to wire (optional): cursor | claude | codex | copilot | gemini | windsurf
- Where to create it: {{./my-product}}

Steps — do them in order, stop and confirm after each numbered step:

1. Scaffold the framework (e.g. `npx create-next-app@latest`), `cd` into the project, init git.
2. Run `npx @logicplanes/specui@latest init` with the name, preset, `--agents-md`, the right
   `--agent-tools`, and `--ci github`.
3. Run `npx specui doctor`. Report any errors or warnings to me before continuing.
4. Ask me 4–6 short questions about the brand: voice, accent color, typography, density,
   light/dark, imagery. Use my answers to fill in `.specui/01-brand-and-product.md`,
   `.specui/02-foundations-tokens.md`, and `.specui/TOKENS.yaml`.
5. Propose the foundation token set (color, type, spacing, radius, shadow, motion) for light
   and dark themes. Wait for my approval before writing.
6. Define the first three to five components we will actually need (e.g. button, input, dialog,
   card, navigation). For each one:
     a. `npx specui add component <name> --variants <…> --states <…>`
     b. Fill in `.specui/components/<name>/SPEC.md`, `STATES.md`, `VARIANTS.md`.
   Stop and confirm with me after each component.
7. Define one or two flow patterns (e.g. onboarding, destructive-confirmation) with
   `npx specui add pattern <name>` and fill them in.
8. `npx specui sync` then `npx specui validate .specui --strict`. Fix every finding; re-run
   until it prints "SpecUI valid — no findings."
9. Optional: if we want shadcn reference source, `npx specui get button` (and similar).
10. Export tokens for the framework: `npx specui export --format {{tailwind | css | dtcg | json}}`
    and wire them into the framework's config so code reads from the same source of truth.
11. Commit `.specui/`, the framework scaffold, and the wiring in a single first commit.

Rules for the rest of this project:
- Never write or modify UI code without first registering the component in `.specui/`.
- Run `specui validate .specui --strict` before considering any UI task done.
- If a token is missing, add it with `specui add token` before using it in code.
- Keep `.specui/` and the implementing code in the same commit.
- Suggest a `specui add component` whenever I describe a UI feature that needs a new piece.

---

Tips for both prompts

• Stop and confirm. Both prompts ask the agent to pause after each step. If your agent tends to barrel through, add "Wait for my reply before continuing" to every numbered step.
• Strict is the point. validate --strict is what turns this from documentation into enforcement. Don't skip it.
• Tailor the questions. Step 4 in each prompt asks the agent to interview you. If you already have a brand guide, point the agent at it instead: "Read BRAND.md instead of asking me; derive tokens from it."
• MCP users. If you've wired the SpecUI MCP server (specui mcp install-hook cursor), the agent can read the spec through the model context protocol directly — but the workflow above still applies.

---

Where to go next

• Agents & MCP — how agents read .specui/, plus rules and skills
• Quick start — the human-driven version of the same flow
• Scenarios — monorepo, design-system repo, agent-first, shadcn
• CI/CD — make validate --strict fail the PR