Skip to content
Back to the portfolio

Rubrica: Open-Source Portfolio Run by AI Agents

  • Astro
  • React
  • TypeScript
  • Convex
  • MCP
  • Claude Code
  • pnpm
  • Changesets
  • GitHub Actions
  • Vercel
  • TailwindCSS
  • Asaas

My role

Author and maintainer of the project, open source under GPL-3.0.

Building a portfolio from scratch is too much work, and off-the-shelf builders make everyone look the same. Rubrica sits in between: the whole technical foundation is already done (home, portfolio, blog, resume, client proposals, admin panel and payments), and an AI agent helps write and maintain the content.

From test drive to live site: on the Rubrica website, you try layouts, colors and fonts on the real app and copy a command. create-rubrica sets up the project, the database and the admin, asking only for the password, and publicar ships it to Vercel.
13 layouts × 15 color schemes, each with light and dark modes, textures and fonts.
Run by AI: the rubrica skill edits the site from plain-language requests, and the strategist skills write the intro, case studies, resume and posts in the owner's voice, starting from a voice interview. Works with Claude Code, Codex and OpenCode.
Client proposals: password-protected links, e-acceptance, handwritten signature and a PDF contract, with Telegram notifications.
Full admin: everything is edited through the UI, including colors, fonts and the site's fixed copy, and 15 plugins turn each feature on or off.
Optional payments: PIX, boleto and card through Asaas. Optional AI for pt-BR/en-US translation and resumes tailored to each job posting.

Under the hood: React + Vite on the front end, Convex as the backend, continuous deployment on Vercel, a public site in Astro, 150 test files with Vitest and mutation testing with Stryker. GPL-3.0 licensed.

Before

v1 was a template: every site got a copy of the whole codebase. Updating meant merging Rubrica's changes with the owner's, file by file. The public site was a Vite SPA rendered in the browser, and the AI skills edited content through a Python script.

The problem

That model had three limits. First, every SEO, accessibility or security fix had to reach each copy of the code, one at a time. Second, an SPA ships an empty page and builds the content in the browser, which matters for a portfolio that lives on being found. Third, v1 had three security flaws in proposals: the worst one let anyone read a password-protected proposal through the API without entering the password.

And the AI agent edited the site through a script that didn't know what each site accepted, without the checks the admin panel runs.

The solution

In v2, Rubrica became a core package (@rubrica/core) with separate themes (@rubrica/theme-*), in a pnpm monorepo. Updating is now bumping a package version, and a fix made once in the core reaches every theme.

The public site ships as static HTML built with Astro, with a sitemap, RSS, hreflang and structured data, and almost no JavaScript: only the interactive parts (contact, filters, search) become React islands. The admin panel is still React and the backend is still Convex. Pages are built from blocks, 21 in the catalog, with a live preview in the panel, and there are two site lines: personal and company.

For agents, I replaced the Python script with a local MCP server. Claude Code or Codex sign in as an admin user, that user's role sets what they can do, and every write starts as a preview. The MCP reads the project's own block catalog and the installed theme's variants, so the agent only builds what the site accepts.

For anyone already on v1, the migrar command creates a branch, swaps the code, converts the data into an import file and lists what the owner customized, without writing to any database.

Decisions and trade-offs

Package instead of template. Owners lose the freedom to edit any core file. To make up for it, they can eject a component into the project or build their own theme, with a guide.

Static Astro instead of an SPA. The site is fast and readable for Google, but new content only shows up on the next build. That's why the panel has a live preview and publishing triggers the deploy.

Local MCP instead of a hosted server. It runs on the owner's machine and shuts down with the agent: no extra service to maintain, and the password stays in their terminal.

A migration that doesn't write. migrar imports into a new development Convex, and production only changes with the owner's ok.

Publishing without a token. Versions are cut with Changesets and published from GitHub Actions with npm trusted publishing (OIDC): no stored token, and provenance on every package.

The results

2.0.0 shipped on November 8, 2026 with 18 packages on npm: the core, the CLI, the MCP server, the theme tester and the 14 themes, all passing the same battery (axe, h1, <head>, JavaScript per page and Lighthouse). The three proposal security flaws are fixed.

I migrated this site, mmlo.com.br, from v1 to v2 with migrar itself: the data went into a new Convex, I checked parity with v1 page by page, and the production switch went in through a PR, live on November 11. I now edit its content through the MCP server, from inside Claude Code. Later versions already ship from GitHub Actions, with no token.

Results by the numbers

  • 18Packages published on npm
  • 70MCP tools for AI agents
  • 14Themes on one test battery
  • 3v1 security flaws fixed
  • 115Test files