Launch checklist and integration workflow for adding a new prototype to the portfolio monorepo. Use when the user wants to: (1) Start a new prototype or portfolio item, (2) Dream up or brainstorm a new project, (3) Plan a new interactive demo, (4) Add a new app to the monorepo. Triggers include phrases like 'new prototype', 'new project', 'new portfolio item', 'add a new app', 'I have an idea for', 'let's build', or any request to create something new in the portfolio.
When a user starts dreaming up a new project, this skill ensures every integration point is handled — nothing falls through the cracks, documentation stays current, and the new prototype leverages existing assets from day one.
Before touching code, gather enough context to shape the work:
newproject.cookinupideas.comUse the breadboarding skill (.claude/skills/breadboarding/SKILL.md) to shape non-trivial features before implementation.
Every new prototype needs these files and updates. Create them as placeholders first, then fill in during implementation.
prototypes/{name}/
├── package.json # @proto-portal/{name}, workspace member
├── vite.config.ts # base: '/prototypes/{name}/', port: {next available}
├── tsconfig.json # Extend from root patterns
├── tailwind.config.ts # Import baseTailwindConfig, add prototype overrides
├── index.html # Vite entry point
├── postcss.config.js # Standard PostCSS with tailwind + autoprefixer
├── src/
│ ├── App.tsx # Main component with Navigation + routes
│ ├── main.tsx # React entry point
│ ├── index.css # Import design tokens CSS
│ ├── components/ # (empty, ready for components)
│ │ └── Navigation.tsx # Top nav matching other prototypes
│ ├── data/ # (if static data needed)
│ └── types.ts # (if custom types needed)
├── e2e/ # Playwright test directory
├── playwright.config.js # Standard Playwright config
├── AGENTS.md # Prototype-specific agent guidance
└── README.md # Prototype documentation
These are the existing files that MUST be updated when adding a new prototype:
| File | What to Add |
|---|---|
Root package.json | Add workspace to workspaces array; add dev:{name} and build:{name} scripts |
scripts/build.sh | Add build step and copy-to-dist step for the new prototype |
terraform/main.tf | Add prototype name to CloudFront Function's hardcoded list |
terraform/route53.tf | Add subdomain record (if using a subdomain) |
shared/api/src/server.js | Add new port to CORS origins (if the prototype has a new port) |
src/components/Portfolio.tsx | Add prototype card to the landing page |
.github/workflows/deploy.yml | Add test step for new prototype (if it has tests) |
Root AGENTS.md | Add to architecture diagram, port reference table |
Root CLAUDE.md | Add to port reference table |
Root README.md | Add to prototypes table, port reference, and structure diagram |
This is the most important part of the skill. Missing any of these means documentation drifts from reality. Update them during scaffolding, not "later."
Every prototype should use the shared design tokens:
/* src/index.css */
@import "@proto-portal/design-tokens/css/tokens.css";
@import "@proto-portal/design-tokens/css/utilities.css";
@tailwind base;
@tailwind components;
@tailwind utilities;
// tailwind.config.ts
import { baseTailwindConfig } from "@proto-portal/design-tokens/tailwind/base-config";
export default {
...baseTailwindConfig,
content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"],
// Add prototype-specific overrides here
};
If the prototype needs a custom theme (like FFX's light mode), create a preset override:
// In shared/design-tokens/index.ts, add to presetOverrides:
export const presetOverrides = {
ffxSkillMap: { /* ... */ },
newPrototype: {
colors: { /* custom colors */ },
// ... other overrides
},
};
Follow the existing patterns:
// package.json test scripts
{
"scripts": {
"test": "jest --passWithNoTests",
"test:watch": "jest --watch --passWithNoTests",
"test:e2e": "playwright test",
"test:e2e:ui": "playwright test --ui",
"test:e2e:headed": "playwright test --headed"
}
}
Create at minimum:
e2e/ directory with a basic smoke test--passWithNoTests until unit tests are added)// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react-swc';
import path from 'path';
export default defineConfig({
plugins: [react()],
base: '/prototypes/{name}/',
server: {
port: {PORT}, // Use next available: check CLAUDE.md port table
host: '::',
},
resolve: {
alias: {
'@': path.resolve(__dirname, './src'),
},
},
});
Add to scripts/build.sh:
echo "Building {Display Name}..."
yarn workspace @proto-portal/{name} build
mkdir -p dist/prototypes/{name}
cp -r prototypes/{name}/dist/* dist/prototypes/{name}/
In terraform/main.tf, add the new prototype name to the CloudFront Function's list:
if (prototypeName === 'ffx-skill-map' || prototypeName === 'home-lending-learning' ||
prototypeName === 'documentation-explorer' || prototypeName === 'learning-path' ||
prototypeName === '{name}') {
Every prototype gets its own AGENTS.md with:
# Agent Instructions: {Display Name}
## What This Prototype Demonstrates
[1-2 paragraphs: what it does and why it matters for a portfolio]
## Architecture Decisions
[Key technical choices and why they were made]
## Key Files
[Table of important files and their purpose]
## Development
[Dev server command, port, test commands]
## Gotchas
[Non-obvious things an agent needs to know]
## Deployment
[Build command, production URL]
## Related
[Links to root AGENTS.md, shared resources used]
Before considering the prototype "launched":
yarn dev:{name} starts the dev serverhttp://localhost:{PORT}/prototypes/{name}/ shows the appyarn build:{name} produces output in dist/prototypes/{name}/yarn dev:proxy) routes to the new prototypeAGENTS.md exists with prototype-specific guidanceThese existing assets can be leveraged in new prototypes:
| Asset | Location | How to Use |
|---|---|---|
| Design tokens | shared/design-tokens/ | CSS imports + Tailwind config extension |
| Claude API proxy | shared/api/ | POST to localhost:3004/api/v1/... |
| Navigation component pattern | Any prototype's Navigation.tsx | Copy and adapt |
| Instructions modal pattern | documentation-explorer/InstructionsModal.tsx | Copy for onboarding |
| Playwright config | Any prototype's playwright.config.js | Copy and update port/base |
| CI test step | .github/workflows/deploy.yml | Add workspace test command |
Current ports in use: 3001, 3002, 3004, 3005, 3006, 7474, 7687, 8080, 8082.
Next available ports: 3007, 3008, 3009.
When allocating a port, update the port reference tables in CLAUDE.md, AGENTS.md, and README.md.