Agentic Programming Specification

Create a build step for the Storybook component library so components can be consumed as an NPM package rather than only being available through the external Storybook instance.

# Add build configuration for component library
# npm install -D vite-plugin-dts
# Configure vite.config.ts in library mode
# Add scripts: "build:lib": "vite build"
# Update package.json with main/module/types fields

Add visual regression testing so that when an agent changes a component, Chromatic automatically catches any unintended visual differences before the PR is merged.

npm install --save-dev chromatic
# Add GitHub Actions workflow:
# - uses: chromaui/action@latest
#   with:
#     projectToken: ${{ secrets.CHROMATIC_TOKEN }}

Move Storybook hosting into the project's own CI/CD pipeline so it builds and publishes automatically, giving agents a reliable reference for component patterns.

# Add to GitHub Actions workflow:
# - name: Build Storybook
#   run: npx storybook build
# - name: Deploy Storybook
#   uses: actions/upload-pages-artifact@v3
#   with: { path: storybook-static }

Create foundational documentation so agents know how to work with the single Express.js server, 11 HTML pages, and Storybook components.

# Create CONTRIBUTING.md in project root
# Must cover:
# 1. Project structure: server.js, public/*.html, Storybook
# 2. How to add new HTML pages
# 3. Express route conventions
# 4. Cookie auth mechanism
# 5. Deployment via Railway

Create a CLAUDE.md that gives AI coding agents immediate context about the project structure, tech stack, and key patterns so they can contribute effectively from the first prompt.

# Create CLAUDE.md in project root
# Cover: tech stack, file structure, auth mechanism,
# deployment, HTML page conventions, Storybook location

Install the foundational test runner so the Express server can run tests. Without this, there is zero ability to verify any code change — this is the single biggest blocker to agentic programming.

npm install -D jest supertest
# Create jest.config.js
# Add to package.json scripts:
# "test": "jest",
# "test:coverage": "jest --coverage"
# Create first test: test/server.test.js
# const request = require('supertest');
# const app = require('./server');
# describe('GET /login', () => {
#   it('returns login page', async () => {
#     const res = await request(app).get('/login');
#     expect(res.status).toBe(200);
#   });
# });

Write integration tests for the Express server routes using Supertest. Cover the auth flow (cookie-based login with password dino2026), protected page access, and static file serving.

# Create test/routes.test.js:
# Test login with correct password returns cookie
# Test login with wrong password returns error
# Test protected pages redirect without cookie
# Test all 11 HTML pages return 200 with valid cookie

Add Playwright E2E tests to verify the HTML pages render correctly in a browser and the login flow works end-to-end.

npm install -D @playwright/test
npx playwright install
# Create e2e/pages.spec.ts:
# Navigate to each HTML page, verify title and key elements
# Test login flow with password authentication

Install ESLint and Prettier so the project has baseline code quality enforcement. This is essential for agents to produce consistent code.

npm install -D eslint prettier eslint-plugin-security eslint-config-prettier
# Create .eslintrc.js with Node.js rules
# Create .prettierrc
# Add to package.json: "lint": "eslint .",  "format": "prettier --write ."
# Run: npx eslint . --fix

Add pre-commit hooks so every commit is auto-formatted and linted. This prevents agents from committing code that doesn't match the project's style.

npm install -D husky lint-staged
npx husky init
# Add to package.json:
# "lint-staged": { "*.js": ["prettier --write", "eslint --fix"], "*.html": ["prettier --write"] }
# Create .husky/pre-commit: npx lint-staged

Initialize a git repo so the project has version control. Without this, there is no way for agents to create branches, open PRs, or track changes.

git init
# Create .gitignore: node_modules/, .env, *.log
git add .
git commit -m "feat: initial commit"
# Create GitHub repo and push
# Create .github/PULL_REQUEST_TEMPLATE.md

Set up branch protection and conventional commits so agents follow a structured workflow when contributing code.

npm install -D @commitlint/cli @commitlint/config-conventional
# Create commitlint.config.js
# Add Husky commit-msg hook
# Configure GitHub branch protection rules via Settings

Create a CI workflow that blocks PRs unless lint and tests pass. This gives agents immediate feedback on code quality.

# Create .github/workflows/ci.yml:
name: CI Quality Gate
on:
  pull_request:
    branches: [main]
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 18, cache: npm }
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: node server.js & sleep 2 && curl -f http://localhost:3000/login

Connect Railway to the GitHub repo so deployments happen automatically on merge to main. This eliminates the manual railway up step.

# Connect Railway to GitHub repo:
# railway link --environment production
# Enable auto-deploy in Railway dashboard
# Configure health check endpoint

Add automated static security scanning and dependency auditing so every PR gets checked for vulnerabilities. This is especially critical when AI agents generate code.

# Create .github/workflows/codeql.yml:
name: CodeQL Analysis
on:
  pull_request:
    branches: [main]
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: github/codeql-action/init@v3
        with: { languages: javascript }
      - uses: github/codeql-action/analyze@v3
# Also add: npm audit --production --audit-level=high

Replace the plaintext password check with bcrypt hashing, add rate limiting to the login endpoint, and install gitleaks to prevent secrets from being committed.

npm install bcrypt express-rate-limit helmet
# Hash password with bcrypt instead of plaintext comparison
# Add helmet() middleware for security headers
# Add rate limiting to /login endpoint
# Install gitleaks: brew install gitleaks
# Add pre-commit hook for secret detection

Document all Express routes in server.js so agents know every endpoint, its method, authentication requirements, and response. Add a health check for monitoring.

# Add JSDoc comments to each route in server.js
# Add GET /health endpoint:
# app.get('/health', (req, res) => res.json({ status: 'ok', uptime: process.uptime() }));
# Document: login POST, logout, static serving, protected routes

Add Swagger UI so the Express server's routes are self-documenting and agents can reference the API contract directly.

npm install swagger-ui-express swagger-jsdoc
# Add swagger-jsdoc annotations to server.js routes
# Serve Swagger UI at /api-docs

Extract all hardcoded configuration from server.js into environment variables. The app currently hardcodes PORT (3000) and the auth password ("dino2026"). Without env vars, agents cannot configure the app for different environments.

# Install dotenv:
# npm install dotenv
# Create .env.example:
# PORT=3000
# AUTH_PASSWORD=your_password_here
# COOKIE_SECRET=your_cookie_secret_here
# NODE_ENV=development
#
# Update server.js:
# require('dotenv').config();
# const PORT = process.env.PORT || 3000;
# const AUTH_PASSWORD = process.env.AUTH_PASSWORD || 'dino2026';
# app.listen(PORT, () => console.log(`Server running on port ${PORT}`));

Add a health check endpoint and pin the Node.js version. Railway needs a health endpoint to monitor the service, and version pinning prevents "works on my machine" issues when agents or developers use different Node versions.

# Add to server.js:
# app.get('/health', (req, res) => {
#   res.json({
#     status: 'ok',
#     uptime: process.uptime(),
#     timestamp: new Date().toISOString(),
#     version: require('./package.json').version
#   });
# });
#
# Create .nvmrc:
# 20
#
# Add to package.json:
# "engines": { "node": ">=20.0.0" }

Document the complete Express route map and authentication flow. The app uses cookie-based auth with a single password. Agents need to understand which routes exist, which are protected, and how the auth cookie works to add new pages or API endpoints correctly.

# Read server.js and document all routes:
# GET / → redirects to /login or /index.html based on auth
# POST /login → validates password, sets cookie, redirects
# GET /logout → clears cookie, redirects to /login
# Static: public/*.html served via express.static
#
# Auth flow:
# 1. User visits any page
# 2. Middleware checks for auth cookie
# 3. If no cookie → redirect to /login
# 4. POST /login with password "dino2026"
# 5. Cookie set → redirect to /index.html

Map the navigation structure of all 11 HTML pages and add error handling. Currently there is no 404 page or error middleware — agents need to know the full page inventory and navigation paths to add new pages that integrate correctly.

# Inventory all pages in public/:
# index.html, prospectus.html, architecture.html,
# agentic-spec.html, etc.
# For each page, document:
# - Purpose/description
# - Navigation links to other pages
# - Whether it requires authentication
#
# Add error handling to server.js:
# app.use((req, res) => {
#   res.status(404).sendFile('public/404.html');
# });
# app.use((err, req, res, next) => {
#   console.error(err);
#   res.status(500).json({ error: 'Internal server error' });
# });