Agent blueprint

Human usage: copy this page URL and tell the agent:

Ejecuta https://auradesignsystem.com/docs/mcp-agent-blueprint

(Local docs: http://localhost:4000/docs/mcp-agent-blueprint.)

This page is an agent runbook, not the CLI command aura blueprint. The runbook may invoke that command when the project is missing its wiki, image-generation command, preflight, Sonar scaffolding, or gdp-ts proofs.

Agent: follow this runbook

If the user pasted this URL with Ejecuta, Run, Execute, or Aplica, you are the agent. Do not only explain. Audit the workspace, install what is missing, and report.

Default target: consumer project (an app using Aura). Only use the Aura monorepo registry path if the repo clearly is aura-design-system (has packages/registry/registry/default/components/).

0. Preconditions

• Work in the project root that has (or will have) package.json / the Next app.
• Prefer non-interactive installs: pnpm dlx ….
• Do not invent secrets. Do not force-push.
• If components.json is missing and the app is not Next-like, say what blocked you and stop after the audit.

1. Audit (read before write)

Check and record present / missing for each:

Also note: Tailwind/Aura CSS already applied? (globals.css with accent/gray scales, or prior aura setup / init).

Cloud agents: marketplace plugins may not load reliably on cloud VMs. Prefer detecting repo-local skill / AGENTS.md, and report plugin unknown on cloud VM honestly — never claim pstack is installed if /poteto-mode does not resolve.

2. Install / fix gaps

Apply only what is missing. Prefer the smallest fix.

A. Full Aura apply (no Aura yet, or heavily incomplete)

pnpm dlx @aura-design/cli@latest setup

(setup updates components.json, globals.css, adds registry packages, rules, skills, and runs CLI blueprint scaffolding. Use from the app root.)

If the user only wants AI context (not full theme rewrite), skip setup and use the targeted adds below.

B. Targeted AI context (typical “old project already on Aura”)

pnpm dlx shadcn@latest add \
  @aura/rules \
  @aura/skills \
  @aura/rule-design-md \
  @aura/eslint-shadcn-lint

• @aura/rules → .cursor/rules/
• @aura/skills → .cursor/skills/ (includes port-component-to-aura and generate-brand-images)
• @aura/rule-design-md → rule + root DESIGN.md
• @aura/eslint-shadcn-lint → eslint.aura-shadcn.mjs + .cursor/rules/shadcn-lint.mdc (see D below)

If the blueprint wiki, Image-Identity.md, or pnpm ai:image is missing, scaffold those project capabilities without rewriting the Aura theme:

pnpm dlx @aura-design/cli@latest blueprint .

Ensure components.json has:

"registries": {
  "@aura": "https://auradesignsystem.com/r/{name}.json"
}

(Optional local registry while developing Aura itself: "@aura-dev": "http://localhost:4000/r/{name}.json".)

C. MCP config (create if missing)

Write project .cursor/mcp.json if absent:

{
  "mcpServers": {
    "shadcn": {
      "command": "npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

Then tell the user (you cannot finish this in the terminal):

1. Restart Cursor or reload MCP.
2. Settings → MCP → enable shadcn (green dot).

D. @shadcn/lint (Aura Tailwind policy for agents)

Machine-checks design-system usage so agents get fixable errors (not only prose rules). Requires ESLint ≥ 9.30 and Node ≥ 20.19.

If missing:

pnpm add -D @shadcn/lint
pnpm dlx shadcn@latest add @aura/eslint-shadcn-lint

(@aura/rule-shadcn-lint installs the same pair: Cursor rule + eslint.aura-shadcn.mjs.)

Merge into the app’s eslint.config.mjs (do not replace an existing Next/ESLint setup):

import { plugin as shadcn } from "@shadcn/lint"
import {
  createAuraShadcnLintConfig,
} from "./eslint.aura-shadcn.mjs"

export default [
  ...existingConfig,
  ...createAuraShadcnLintConfig(shadcn),
]

Policy shipped at warn:

Keep no-restyle / no-arbitrary-values off under components/ui/**. Ensure package.json has a lint script; after UI work, run it and fix findings. Promote rules to error once the warning baseline is under control.

Upstream: shadcn-ui/lint. Docs: Lint.

E. pstack (agent rigor / poteto-mode)

Additive agent-rigor layer (verification + playbooks). It does not replace @aura/rules, Aura skills, DESIGN.md, shadcn MCP, or @shadcn/lint.

When to install: Always offer when missing on an Aura consumer or aura-monorepo workspace where the user is using Cursor agents. Skip only if the user said “Aura UI context only, no pstack.”

Easy path (preferred) — Cursor marketplace plugin pstack (id 9717366). Prefer this over vendoring backnotprop/pstack into apps:

1. In Cursor chat on this project: /add-plugin pstack
2. Pick pstack in the plugin picker
3. /setup-pstack
4. Start a new chat
5. Smoke: /poteto-mode <small read-only task>. Done means <checkable>. Do not edit unless asked.

Aura monorepo: if scenario is aura-monorepo, link root AGENTS.md (and .cursor/skills/aura-constraints/, .cursor/skills/aura-verification/) — do not duplicate a full pstack vendor into the registry.

Cloud agent note: If /poteto-mode is not found on a cloud agent, say so in the result table. Workarounds: (1) open cursor.com/agents and prompt “use /poteto-mode (pstack) …”; (2) optional thin .cursor/skills/poteto-mode/SKILL.md committed only when the team opts in — do not auto-vendor the full plugin.

Grok Bot note: Account install of marketplace plugin 9717366 enables pstack skills for Grok Bots; still run /setup-pstack in Cursor IDE for local model roles.

Do not: git clone pstack into node_modules or app src/; do not replace Aura lint/rules with pstack principles.

F. gdp-ts (proof-carrying authz)

Every sensitive function takes a typed proof that the check already ran for those ids. Proofs are never cast. CI is pnpm typecheck and pnpm lint. This does not replace a policy engine, Aura rules, @shadcn/lint, or pstack. See gdp-ts.

When to install: Whenever @gdp-ts/core, the ESLint preset, the skill, or the starter proofs are missing. Skip only if the user said “no gdp-ts”.

aura init and aura setup already run this. On an existing app, re-run blueprint (it skips files that exist):

pnpm dlx @aura-design/cli@latest blueprint .

That installs @gdp-ts/core, spreads @gdp-ts/core/lint/eslint into the flat ESLint config, runs:

npx skills add rauchg/gdp-ts --skill gdp-ts -a cursor -y --copy

and writes lib/ids.ts, lib/authz-store.ts, proofs/*, and data/delete-project.ts (plus the handler and data/mistakes.ts) under the @/ root.

Do not: vendor the skill into the Aura registry, cast as Proof, export a prover, or call defineProof outside proofs/. The default preset is not strict mode; do not turn on strict: true in an app that still uses as for unrelated code. Replace lib/authz-store.ts with the real database before shipping. The in-memory maps are a stand-in, and handlers must not write roles into them.

3. Verify

Confirm after installs:

• .cursor/rules/ has Aura foundation rules
• .cursor/skills/port-component-to-aura/SKILL.md exists
• .cursor/skills/generate-brand-images/SKILL.md and its generator script exist
• wiki/obsidian-*/01-Identity/Image-Identity.md exists
• package.json has ai:image; .env.example names GOOGLE_API_KEY
• Root DESIGN.md exists (or user declined design-md)
• components.json includes @aura
• .cursor/mcp.json has shadcn MCP (user must enable in UI)
• @shadcn/lint installed; eslint.config.* spreads createAuraShadcnLintConfig (or equivalent); eslint.aura-shadcn.mjs / shadcn-lint rule present when using the registry item
• pstack available: /poteto-mode resolves in this environment or documented missing with reason (local plugin / cloud gap / user skipped)
• If installed (or install was offered): agent can state that /setup-pstack was offered or completed
• @gdp-ts/core is installed; the ESLint preset is spread into the flat config (or eslint.gdp-ts.mjs exists and the gap is named); .agents/skills/gdp-ts/SKILL.md or .cursor/skills/gdp-ts/SKILL.md exists; data/delete-project.ts demands session, project-role, and plan proofs

Optional smoke: pnpm dlx shadcn@latest add @aura/button only if the user asked to install a component; do not add random UI.

4. How to work after setup

• Consumer app: follow the skill port-component-to-aura in project mode — write into @/components aliases; do not create Ladle/registry metadata.
• Aura monorepo: skill registry mode — component + Ladle Default story + metadata/{kebab}.yml + registry:generate / registry:build.
• Landing with images: follow generate-brand-images. Read the blueprint 01-Identity notes first. If image identity is undefined, ask focused identity questions and update Image-Identity.md before generating.
• Gemini access: the bundled command reads GOOGLE_API_KEY or GEMINI_API_KEY directly from root .env. If absent, ask whether the user wants to add a key, use agent-native image generation when available, or continue with placeholders; never fabricate a key.
• Batch landing flow: inspect the landing, create one manifest for the necessary image set, run pnpm ai:image -- --manifest <path>, integrate accepted local assets, then record their paths in the wiki.
• Mobile form UX (critical): input / textarea / select font-size MUST be ≥ 17px. Never put text-sm or text-xs on editable fields—iOS Safari zooms on focus below that size. Keep html { font-size: 17px; } and the global floor in styles/main.css (font-size: max(1rem, 17px)). See Typography rules and DESIGN.md.
• Design lint: after UI edits, run pnpm lint (or the app’s lint script) and clear @shadcn/lint warnings. Form controls own padding — add a size/variant on the component if spacing must change.
• Hard engineering / multi-step changes: prefer /poteto-mode (pstack) with an explicit Done means check. Keep Aura skills for porting components (port-component-to-aura), brand images, and DESIGN.md. Use @shadcn/lint + Aura rules as the Gardener gates; use pstack for playbooks + verification. After UI edits still run pnpm lint.
• Sensitive APIs: follow the gdp-ts skill. A function that reads or changes something only some callers may touch takes a proof about its named arguments. Never cast a proof. After authz edits, run pnpm typecheck and pnpm lint.
• Verification skill (optional): /create-verification-skill is project-local. Inside the Aura monorepo it should target Aura surfaces (Ladle stories, token docs, package exports) — not product-app flows unless the consumer asks.
• Concepts: MCP overview · Rules · Installation

5. Final reply to the user (required format)

## Agent blueprint — result

**Project:** <path or package name>
**Scenario:** consumer | aura-monorepo

| Check | Before | Action | After |
| --- | --- | --- | --- |
| components.json @aura | … | … | … |
| DESIGN.md | … | … | … |
| .cursor/rules | … | … | … |
| .cursor/skills | … | … | … |
| Blueprint image identity | … | … | … |
| Gemini image command | … | … | … |
| .cursor/mcp.json | … | … | … |
| @shadcn/lint + Aura eslint fragment | … | … | … |
| pstack / poteto-mode | … | … | … |
| pstack-models setup (optional) | … | … | … |
| @gdp-ts/core | … | … | … |
| gdp-ts ESLint preset | … | … | … |
| gdp-ts skill | … | … | … |
| gdp-ts proofs (`deleteProject`) | … | … | … |

**Manual step for you:** enable shadcn MCP in Cursor
Settings (if not already green). If pstack was offered,
finish `/add-plugin pstack` → `/setup-pstack` in Cursor desktop
when you are not already set up.

**Next:** paste a component URL to port it, or
describe a landing page; the agent can plan and
generate its identity-aligned image set. For rigorous /
multi-step changes, paste a `/poteto-mode … Done means …`
task after the blueprint finishes.

Stop when the table is accurate. Do not claim MCP is connected if the user still needs to flip the Settings toggle. Do not claim pstack//poteto-mode is available if the plugin did not resolve (especially on cloud agents).

Related

• pstack — what /poteto-mode is, why Aura uses it, easy install
• gdp-ts — proof-carrying authz, starter proofs, CI typecheck + lint
• Lint — @shadcn/lint setup and Aura policy
• MCP — what MCP/skills/rules are
• Rules — install @aura/rules
• Installation — aura CLI init
• CLI aura blueprint — wiki, preflight, Sonar, and gdp-ts scaffolding (not this runbook)