New Prototype Launch Skill

Every new prototype needs these files and updates. Create them as placeholders first, then fill in during implementation.

Files to Create

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

Integration Checklist

These are the existing files that MUST be updated when adding a new prototype:

This is the most important part of the skill. Missing any of these means documentation drifts from reality. Update them during scaffolding, not "later."

Phase 3: Integrate Design System

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
  },
};

Phase 4: Set Up Testing

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
• Jest config (or --passWithNoTests until unit tests are added)

Phase 5: Configure Deployment

Vite Config

// 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'),
    },
  },
});

Build Script Update

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}/

CloudFront Function Update

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}') {

Phase 6: Write AGENTS.md

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]

Phase 7: Verify

Before considering the prototype "launched":

• yarn dev:{name} starts the dev server
• Navigating to http://localhost:{PORT}/prototypes/{name}/ shows the app
• yarn build:{name} produces output in dist/prototypes/{name}/
• The dev proxy (yarn dev:proxy) routes to the new prototype
• All integration checklist files have been updated
• AGENTS.md exists with prototype-specific guidance
• Portfolio landing page links to the new prototype

Reusable Assets

These existing assets can be leveraged in new prototypes:

Port Allocation

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.