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 feature map, 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/).

Update an existing project

An existing project has any of these: .agents/, .cursor/rules, .cursor/skills, wiki/obsidian-*, components.json with @aura, DESIGN.md, or sonar-project.properties. For an existing project:

1. MUST NOT run aura init or aura setup. They rewrite components.json and globals.css and would replace a customized theme.

2. Run the latest blueprint from the project root:

   npx @aura-design/cli@latest blueprint .

   It keeps team-owned files (package.json entries, scripts/preflight.ts, sonar-project.properties, scripts/sonar.sh, bruno/, gdp-ts proofs, Image-Identity.md), writes rules and skills that are missing, keeps the ones that exist (the forms skill files are updated when they are an unmodified older Aura copy), moves .cursor/rules into .agents/rules, and deletes retired files: Project Brain and older Emil and Vercel skill copies.

3. Pass --force only when the user wants the latest Aura rules and skills over the existing copies. It overwrites Aura-owned rules, skills, and vault config, including customized ones. It never touches the team-owned files above.

4. Continue with the audit below and install only the rows still missing. Report the stack: and modules: lines blueprint printed.

0. Preconditions

• Work in the project root: the folder with package.json, pyproject.toml, go.mod, pom.xml, *.csproj, composer.json, Gemfile, or Cargo.toml.
• Prefer non-interactive installs: pnpm dlx ….
• Do not invent secrets. Do not force-push.
• If the project is not a JavaScript frontend (Python, Go, Java/Kotlin, .NET, PHP, Ruby, Rust, or anything else), skip the Aura UI rows (components.json, DESIGN.md, shadcn MCP, @shadcn/lint, forms) and gdp-ts. Audit and install only what applies to that stack, then run npx @aura-design/cli@latest blueprint .. It detects the stack and adds the agent rules and the feature map everywhere, Sonar where SonarQube can scan the language, a Bruno collection for backends, and image generation for frontends. Report the stack and the modules it printed.

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/skill-aura \
  @aura/rules \
  @aura/skills \
  @aura/rule-design-md \
  @aura/eslint-shadcn-lint

Or install the design skill with the skills CLI:

pnpm dlx skills add somosgented/aura-design-system --skill aura

• @aura/skill-aura → .agents/skills/aura/ (design guardrails)
• @aura/rules → .agents/rules/ (feature map, no comments, DESIGN.md pointer)
• @aura/skills → .agents/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 (see D below). Lint policy text is in the Aura skill

.agents/ is the one home for agent files. aura blueprint writes rules to .agents/rules/, skills to .agents/skills/, and a managed block in the root AGENTS.md that points every agent there, plus CLAUDE.md with @AGENTS.md. It moves .cursor/rules/* and .cursor/skills/* into .agents/. A differing duplicate stays in .cursor/skills/ with a warning: merge it into .agents/skills/ by hand, then delete it. Never write a new rule or skill under .cursor/.

.agents/skills/aura/SKILL.md is the Aura design skill. Its rules/*.md files are references that skill links to, same as .agents/skills/shadcn/. No agent applies those markdown files every turn. Always-on process rules stay in .agents/rules/*.mdc. @aura/skills installs procedure skills (port-component-to-aura, verify-aura-ui, aura-forms) to .agents/skills/.

If the feature map, 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)

MCP config is the one agent file that stays in the tool's folder, because each client reads its own path. Write the project config for the agent in use, if absent:

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

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

1. Restart the agent or reload MCP.
2. Enable shadcn in the client's MCP settings.

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

That installs eslint.aura-shadcn.mjs. The matching agent text is .agents/skills/aura/rules/lint.md (@aura/skill-aura).

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 .agents/skills/aura-constraints/, .agents/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 .agents/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. Audits

Do not install audits during setup. Record what exists, and install a third-party audit only when the user asks for that review.

• Built in: confirm the gates for the stack. pnpm lint with @shadcn/lint on JavaScript frontends. sonar-project.properties with sonar:* scripts on Node, or scripts/sonar.sh on Python, Go, Java/Kotlin, .NET, PHP, and Ruby. bruno/ on backends. gdp-ts on Node and TypeScript.
• Third-party: Emil Kowalski's skills, vercel-react-best-practices, and workos are not part of Aura. Blueprint deletes the Emil and Vercel folders an older CLI copied into .cursor/skills/ and .agents/skills/. Do not commit or vendor them.

Which audit fits which change, the procedure, the findings format, and the commands are on Audits.

G. 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 feature-map, identity, and proof files that exist, and removes the retired Project Brain rule, skill, and script):

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

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

pnpm dlx skills add shadcn/ui -a cursor -y --copy
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. Aura Keep invariants in .agents/skills/aura/ win when the upstream shadcn skill conflicts (icons, forms, 13px spacing, typography).

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:

• .agents/skills/aura/SKILL.md exists when @aura/skill-aura or skills add was used
• .agents/rules/ has the always-on process rules (feature-map, no-comments, design-md) when @aura/rules was installed
• .cursor/rules and .cursor/skills are absent, or the only leftovers are differing duplicates named in the report
• Root AGENTS.md has the aura:agents block and CLAUDE.md has @AGENTS.md
• .agents/rules/feature-map.mdc, .agents/rules/no-comments.mdc, .agents/skills/update-feature-map/SKILL.md, and wiki/obsidian-*/02-Documentación/Feature-Map/Feature-Map.base exist on every stack
• Sonar: sonar-project.properties plus sonar:* scripts on Node, or scripts/sonar.sh on Python, Go, Java/Kotlin, PHP, and Ruby; scripts/sonar.sh without properties on .NET; nothing on Rust or unknown stacks
• Backends: bruno/bruno.json, bruno/environments/local.bru, and .agents/rules/bruno.mdc exist, and .gitignore has bruno/.env
• The checks below about components, forms, images, lint, MCP, and gdp-ts apply to JavaScript projects only
• .agents/skills/port-component-to-aura/SKILL.md exists
• .agents/skills/generate-brand-images/SKILL.md and its generator script exist on frontends
• .agents/skills/verify-aura-ui/SKILL.md and .agents/skills/update-feature-map/SKILL.md exist when @aura/skills was added
• .cursor/skills/ and .agents/skills/ do not contain emil-design-eng, react-best-practices, or vercel-react-best-practices unless someone installed that audit for this task and has not committed it
• .agents/skills/aura/rules/forms.md, .agents/skills/aura-forms/SKILL.md, and the form, field, use-dynamic-form, and web-validation registry items exist
• .agents/skills/shadcn/SKILL.md exists (or document the gap)
• wiki/obsidian-*/ has 00-General/, 01-Identidad/, 02-Documentación/Feature-Map/Feature-Map.base, and 03-Configuración/; frontends also have 01-Identidad/Image-Identity.md
• .gitignore has wiki/**/.obsidian/ and git ls-files wiki lists no .obsidian/ file (otherwise run git rm -r --cached wiki/*/.obsidian)
• package.json has ai:image and no brain:progress; .env.example names GOOGLE_API_KEY
• Root DESIGN.md exists (or user declined design-md)
• components.json includes @aura
• The agent's MCP config has the shadcn server (user must enable it in the client)
• @shadcn/lint installed; eslint.config.* spreads createAuraShadcnLintConfig (or equivalent); eslint.aura-shadcn.mjs 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 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-Identidad 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 the Aura skill 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
**Stack:** <stack and modules printed by aura blueprint>

| Check | Before | Action | After |
| --- | --- | --- | --- |
| components.json @aura | … | … | … |
| DESIGN.md | … | … | … |
| .agents/skills/aura | … | … | … |
| .agents/rules | … | … | … |
| .agents/skills | … | … | … |
| Feature map + agent rules + vault sections | … | … | … |
| Sonar (when the stack is scannable) | … | … | … |
| Bruno (backends) | … | … | … |
| Third-party audits | … | … | … |
| Forms stack (forms.md, aura-forms, components) | … | … | … |
| Blueprint image identity | … | … | … |
| Gemini image command | … | … | … |
| AGENTS.md entry + .cursor migration | … | … | … |
| MCP config | … | … | … |
| @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
• Audits — third-party Emil, Vercel, and WorkOS skills, installed from upstream when someone asks
• Lint — @shadcn/lint setup and Aura policy
• MCP — what MCP/skills/rules are
• Rules — install @aura/rules
• Installation — aura CLI init
• CLI aura blueprint — feature map, preflight, Sonar, and gdp-ts scaffolding (not this runbook)