VA Form Tool - Technical Specification

Executive Summary

The VA Form Tool is an enterprise-grade AI-powered application that automates the creation of VA.gov Simple Forms. It transforms PDF form documents into production-ready React applications using Claude Opus 4.1, multi-agent orchestration, and pattern-based code generation.

Key Metrics:

• Generation Speed: 2 minutes for a 25-page form (5x faster than single-agent approach)
• Success Rate: 95%+ for forms with gold standard examples
• Code Quality: Automated verification with 9 categories of checks
• Scale: Supports forms from 1-50 pages with conditional logic and array builders

---

Table of Contents

1. Architecture Overview
2. Core Features
3. Multi-Agent System
4. Technology Stack
5. API Reference
6. User Workflows
7. AI/ML Pipeline
8. Integration Points
9. Code Generation
10. Verification System
11. Performance & Scalability
12. Security & Privacy

---

1. Architecture Overview

1.1 System Architecture

┌─────────────────────────────────────────────────────────────┐
│                     VA Form Tool                             │
│  ┌────────────┐  ┌─────────────┐  ┌──────────────────────┐ │
│  │ Next.js UI │  │   API Layer │  │  AI Multi-Agent      │ │
│  │  (React)   │◄─┤  (20 routes)├─►│  Orchestrator        │ │
│  └────────────┘  └─────────────┘  └──────────────────────┘ │
│         │               │                    │               │
│         ▼               ▼                    ▼               │
│  ┌────────────┐  ┌─────────────┐  ┌──────────────────────┐ │
│  │   Wizard   │  │ PDF Process │  │  Pattern Analyzer    │ │
│  │  6 Steps   │  │   (pdftk)   │  │  Gold Standards      │ │
│  └────────────┘  └─────────────┘  └──────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
        ┌──────────────────────────────────────────┐
        │        External Integrations             │
        │  ┌────────────┐  ┌────────────────────┐ │
        │  │ vets-      │  │  Anthropic API     │ │
        │  │ website    │  │  Claude Opus 4.1   │ │
        │  └────────────┘  └────────────────────┘ │
        │  ┌────────────┐  ┌────────────────────┐ │
        │  │ VADS MCP   │  │  Blueprint Library │ │
        │  │  Server    │  │  (8 forms)         │ │
        │  └────────────┘  └────────────────────┘ │
        └──────────────────────────────────────────┘

1.2 Technology Layers

Presentation Layer

• Next.js 14 App Router
• React 18 with TypeScript
• Tailwind CSS 4.1
• Radix UI + shadcn/ui components

Business Logic Layer

• AI orchestration (multi-agent pipeline)
• Pattern matching and analysis
• Code generation and verification
• PDF processing and field extraction

Data Layer

• File-based job storage (JSON)
• Blueprint library (8 pre-built forms)
• Gold standard indexing
• Feedback collection (JSONL)

Integration Layer

• vets-website repository
• Anthropic API (Claude models)
• VADS MCP Server
• pdftk (PDF processing)

---

2. Core Features

2.1 PDF Processing & Field Extraction

Capabilities:

• Upload VA form PDFs (drag-and-drop, up to 50MB)
• Extract form fields using two methods:
  • pdftk: Native PDF field extraction (fastest)
  • AI Analysis: Claude Opus analyzes PDF text and structure
• Extract metadata: title, form number, subject, author, creation date
• Auto-detect VA form numbers from content
• Generate PDF previews (first page only)

Implementation:

• /lib/pdf-processor.ts (1,009 lines) - Main orchestration
• /lib/pdftk-extractor.ts (631 lines) - pdftk integration
• /lib/va-form-analyzer.ts (212 lines) - AI-powered analysis
• /app/api/upload/route.ts - Upload endpoint with streaming

Output:

{
  formNumber: "21P-530",
  title: "Application for Burial Benefits",
  fields: [
    { name: "veteranFullName", type: "text", page: 1 },
    { name: "veteranSSN", type: "ssn", page: 1 }
  ],
  metadata: { author: "VA", creationDate: "2023-01-01" }
}

2.2 Yeoman Scaffold Generation

Purpose: Creates the base VA Simple Form scaffold in vets-website

Why Not Native Yeoman?

• Yeoman requires interactive prompts
• Cannot run non-interactively
• Sub-generators don't receive all options
• PTY/stdin workarounds fail in Next.js

Solution: YeomanFallback

• Custom generator that creates all required files
• Generates 10+ files programmatically
• Tries native Yeoman first, falls back automatically

Generated Files:

1. manifest.json - App metadata and routing
2. app-entry.jsx - Webpack entry point
3. routes.jsx - React Router configuration
4. reducers/index.js - Redux store
5. sass/{form-name}.scss - Form-specific styles
6. containers/App.jsx - Main container with save-in-progress
7. containers/IntroductionPage.jsx - Landing page
8. containers/ConfirmationPage.jsx - Submission confirmation
9. config/form.js - Form configuration (chapters, pages)
10. pages/nameAndDateOfBirth.js - Sample page
11. config/prefill-transformer.js - Data prefill logic
12. config/submit-transformer.js - Submission payload transformation

Implementation:

• /lib/yeoman-fallback.ts (488 lines)
• /lib/yeoman-runner.ts (180 lines) - Tries native first
• /scripts/run-yeoman.js - Standalone Yeoman script
• /app/api/yeoman/execute/route.ts - API endpoint

2.3 Pattern Matching & Gold Standards

Gold Standard Discovery:

• Searches vets-website for similar forms
• Analyzes 200+ existing forms
• Scores by similarity (category, complexity, features)
• Extracts reusable patterns

Similarity Scoring:

score =
  categoryMatch * 40 +        // Same category (pension, disability, etc.)
  complexityMatch * 20 +      // Similar complexity level
  featureOverlap * 30 +       // Shared features (arrays, conditionals)
  formPrefixMatch * 10        // Form number prefix similarity

Pattern Catalog (50+ patterns):

• fullNameUI + fullNameSchema
• addressUI + addressSchema
• dateOfBirthUI + dateOfBirthSchema
• ssnUI + ssnSchema
• phoneUI + phoneSchema
• emailUI + emailSchema
• yesNoUI + yesNoSchema
• arrayBuilderPages (for repeating items)
• fileUploadUI + fileUploadSchema
• And 40+ more...

Implementation:

• /lib/pattern-analyzer.ts (921 lines)
• /lib/gold-standard-index.ts (172 lines)
• /app/api/gold-standards/search/route.ts

2.4 AI-Powered Page Generation

Two Approaches:

Legacy (Single-Agent):

• One AI call generates all pages
• 10+ minutes for complex forms
• Higher chance of errors
• Harder to debug

Modern (Multi-Agent):

• Specialized agents work in parallel
• 2 minutes for 25-page form
• Higher reliability
• Clear error isolation
• 5x faster

Generated Code:

// Example generated page
import { titleUI, fullNameUI, fullNameSchema } from 'platform/forms-system/src/js/web-component-patterns';

export default {
  uiSchema: {
    ...titleUI('Veteran information'),
    veteranFullName: fullNameUI(),
  },
  schema: {
    type: 'object',
    properties: {
      veteranFullName: fullNameSchema,
    },
    required: ['veteranFullName'],
  },
};

Implementation:

• /lib/page-generator.ts (1,923 lines) - Legacy single-agent
• /lib/agents/multi-agent-orchestrator.ts - Modern orchestrator
• /app/api/pages/generate/route.ts - Single-agent endpoint
• /app/api/pages/generate-multi-agent/route.ts - Multi-agent endpoint

2.5 Blueprint System

Pre-built Blueprints (8 forms):

1. 21P-0516-1 (Pension claim)
2. 21-4170 (Disability claim)
3. 21P-4171 (Marital status)
4. 21P-601 (Pension application)
5. 21P-0537 (Marital questionnaire)
6. 21P-0518-1 (Burial benefits)
7. 10-10EZ (Health benefits)
8. 22-1990 (Education benefits)

Blueprint Contents:

{
  "formNumber": "21P-530",
  "metadata": { "title": "Burial Benefits", "category": "pension" },
  "chapters": [
    {
      "id": "veteranInfo",
      "title": "Veteran Information",
      "pages": [
        {
          "id": "veteranDetails",
          "title": "Veteran's details",
          "fields": [
            {
              "fieldName": "veteranFullName",
              "uiPattern": "fullNameUI",
              "schemaPattern": "fullNameSchema",
              "pdfFieldMapping": ["name_first", "name_last"]
            }
          ]
        }
      ]
    }
  ]
}

Benefits:

• Instant plan generation for known forms
• Higher accuracy (based on actual forms)
• Faster field mapping
• Reusable templates

---

3. Multi-Agent System

3.1 Architecture

┌──────────────────────────────────────────────────────┐
│           Multi-Agent Orchestrator                   │
└──────────────────────────────────────────────────────┘
                       │
       ┌───────────────┼────────────────┐
       ▼               ▼                ▼
┌─────────────┐ ┌──────────────┐ ┌──────────────┐
│ Structure   │ │ Page Code    │ │ Import/Export│
│ Planner     │ │ Generator    │ │ Validator    │
│             │ │ (Parallel)   │ │              │
│ ~5 seconds  │ │ ~3-5s/page   │ │ ~5 seconds   │
└─────────────┘ └──────────────┘ └──────────────┘
       │               │                │
       └───────────────┼────────────────┘
                       ▼
              ┌──────────────┐
              │ Integration  │
              │ Tester       │
              │ ~5-10s       │
              └──────────────┘
                       │
                       ▼
              ┌──────────────┐
              │ Write Files  │
              │ to Disk      │
              └──────────────┘

3.2 Agent Responsibilities

Agent 1: Structure Planner

• Input: Extracted fields + blueprint (optional)
• Tasks:
  • Validate form structure
  • Deduplicate fields (field-based + arrayPath-based)
  • Organize into chapters and pages
  • Assign UI/schema patterns
  • Detect conditional logic
• Output: ValidatedPageStructure[]
• Time: ~5 seconds
• Model: Claude Opus 4.1

Agent 2: Page Code Generator (Parallel)

• Input: Single ValidatedPageStructure
• Tasks:
  • Generate page component code
  • Apply UI patterns correctly
  • Handle conditional logic
  • Support array builders
  • Ensure proper export naming
• Output: Generated JavaScript code
• Time: 3-5 seconds per page
• Parallelization: All pages generated simultaneously
• Model: Claude Opus 4.1

Agent 3: Import/Export Validator

• Input: All generated page files
• Tasks:
  • Validate import statements
  • Check export names match usage
  • Fix missing imports
  • Detect hallucinated imports
  • Ensure barrel exports correct
• Output: Fixed page files + validation report
• Time: ~5 seconds
• Model: Claude Sonnet 4.5

Agent 4: Integration Tester

• Input: Generated pages + config/form.js
• Tasks:
  • Test for syntax errors
  • Verify structure integrity
  • Check required fields present
  • Validate conditional logic
  • Test array builder configurations
• Output: Test results + issue list
• Time: 5-10 seconds
• Model: Claude Sonnet 4.5

3.3 Benefits Over Single-Agent

Metric	Single-Agent	Multi-Agent	Improvement
Time (25 pages)	10+ minutes	~2 minutes	5x faster
Success Rate	70%	95%+	+25%
Cost per Form	$2-3	$1-1.50	50% cheaper
Debuggability	Poor	Excellent	Clear agent boundaries
Parallelization	None	Full	All pages at once
Error Isolation	Hard	Easy	Agent-specific errors

3.4 Deduplication Strategy

Problem: AI often generates duplicate fields or pages

Solution: Two-Tier Deduplication

1. Field-Based Deduplication (within a page)

   • Merges fields with same name
   • Preserves all unique properties
   • Combines conditional logic

2. ArrayPath-Based Deduplication (across pages)

   • Identifies duplicate array builders by arrayPath
   • Merges field definitions
   • Prevents duplicate imports

Implementation:

// Field-based dedup
const uniqueFields = Array.from(
  fieldsMap.values()
).map(group => ({
  ...group[0],
  // Merge all unique properties from duplicates
  ...Object.assign({}, ...group)
}))

// ArrayPath-based dedup
const uniquePages = pages.reduce((acc, page) => {
  if (page.isArrayBuilder) {
    const existing = acc.find(p =>
      p.isArrayBuilder &&
      p.arrayConfig?.arrayPath === page.arrayConfig?.arrayPath
    )
    if (existing) {
      // Merge fields
      existing.fields.push(...page.fields)
      return acc
    }
  }
  acc.push(page)
  return acc
}, [])

---

4. Technology Stack

4.1 Frontend

{
  "framework": "Next.js 14 (App Router)",
  "language": "TypeScript 5.3",
  "ui": {
    "library": "React 18",
    "styling": "Tailwind CSS 4.1",
    "components": [
      "Radix UI (primitives)",
      "shadcn/ui (high-level)",
      "lucide-react (icons)",
      "sonner (toasts)"
    ]
  },
  "forms": "react-hook-form + zod",
  "fileUpload": "react-dropzone",
  "codeDisplay": "react-syntax-highlighter",
  "charts": "recharts"
}

4.2 Backend

{
  "runtime": "Node.js 18+ (22+ recommended)",
  "api": "Next.js API Routes",
  "streaming": "Server-Sent Events (SSE)",
  "pdfProcessing": "pdftk + pdftotext",
  "fileOps": "fs/promises (native)"
}

4.3 AI/ML

{
  "provider": "Anthropic",
  "models": {
    "primary": "claude-opus-4-1-20250805",
    "secondary": "claude-sonnet-4-5-20250929"
  },
  "sdk": "@ai-sdk/anthropic + ai (Vercel AI SDK)",
  "contextWindows": {
    "opus": "200K tokens",
    "sonnet": "1M tokens"
  },
  "maxOutput": "64K tokens (both models)"
}

4.4 External Tools

# Required
pdftk           # PDF field extraction
pdftotext       # Text extraction from PDFs

# Optional
git             # For vets-website integration

4.5 Development & Testing

{
  "testing": {
    "framework": "Jest + ts-jest",
    "runner": "Bun (fast) or Node (compatible)",
    "types": [
      "Unit tests",
      "Integration tests",
      "API route tests"
    ]
  },
  "tools": {
    "linting": "ESLint + TypeScript ESLint",
    "formatting": "Prettier",
    "validation": "Zod schemas"
  }
}

---

5. API Reference

5.1 Upload & Jobs

POST /api/upload

• Upload PDF and extract fields
• Supports streaming responses (SSE)
• Max file size: 50MB
• Returns: Job ID

GET /api/jobs

• List all processing jobs
• Returns: Job[] with status

GET /api/jobs/[id]

• Get specific job details
• Returns: Job with extracted fields

DELETE /api/jobs/clear

• Clear jobs older than 24 hours
• Returns: Count of cleared jobs

5.2 Planning & Blueprints

POST /api/generate-plan

• Generate form implementation plan
• Input: Extracted fields + optional blueprint
• Returns: Plan with chapters and pages

POST /api/transform

• Transform fields to submission payload
• Input: Fields + blueprint
• Returns: Transformed payload

GET /api/blueprints

• List available blueprints
• Returns: Blueprint metadata array

5.3 Pattern & Gold Standards

POST /api/patterns/analyze

• Analyze fields and match patterns
• Input: Extracted fields
• Returns: Pattern matches with scores

POST /api/gold-standards/search

• Find similar forms in vets-website
• Input: Form metadata + fields
• Returns: Ranked list of similar forms

GET /api/vads/search?q={query}

• Search VA Design System patterns
• Uses: VADS MCP Server
• Returns: Pattern examples and docs

GET /api/vads/component?name={component}

• Get specific VADS component details
• Returns: Component documentation

5.4 Page Generation

POST /api/pages/generate

• Generate pages (single-agent, legacy)
• Input: Plan + gold standards
• Returns: Generated page files

POST /api/pages/generate-multi-agent

• Generate pages (multi-agent, recommended)
• Input: Plan + gold standards
• Returns: Streaming progress + files

POST /api/pages/verify

• Verify generated code
• Input: Form files
• Returns: Verification results (9 categories)

POST /api/pages/fix

• Auto-fix verification failures
• Input: Verification results
• Returns: Fixed files

POST /api/pages/feedback

• Submit feedback on generated code
• Input: File path + feedback + code snippet
• Returns: Success

GET /api/pages/feedback?formNumber={number}

• Get feedback for a form
• Returns: Feedback entries

5.5 Utilities

POST /api/preview

• Generate PDF preview (first page)
• Input: PDF file
• Returns: Image data URL

POST /api/scaffold

• Execute Yeoman scaffold
• Input: Scaffold configuration
• Returns: Streaming progress + files

---

6. User Workflows

6.1 Quick Extract (Simple)

1. Upload PDF
   ↓
2. Extract fields (pdftk + AI)
   ↓
3. View results
   ↓
4. Export JSON/CSV

Use Case: Just need field data, not full form generation

Time: 30-60 seconds

6.2 Full Wizard (Recommended)

1. Upload & Extract
   ↓
2. Configure Yeoman
   ├─ Form number
   ├─ App name
   ├─ Folder name
   ├─ Tracking prefix
   └─ Template type
   ↓
3. Generate Scaffold
   ├─ Try native Yeoman
   ├─ Fallback if needed
   └─ Create 10+ files
   ↓
4. Find Gold Standards
   ├─ Search vets-website
   ├─ Score by similarity
   └─ Select best matches
   ↓
5. Analyze Patterns
   ├─ Map fields to patterns
   ├─ Detect conditional logic
   ├─ Identify array builders
   └─ Generate structure plan
   ↓
6. Generate Pages (Multi-Agent)
   ├─ Validate structure (5s)
   ├─ Generate pages in parallel (3-5s each)
   ├─ Validate imports/exports (5s)
   └─ Test integration (5-10s)
   ↓
7. Verify & Deploy
   ├─ Run verification checks
   ├─ Auto-fix issues
   └─ Ready for development

Use Case: Complete form generation from PDF to production-ready code

Time: 5-10 minutes (mostly AI generation)

6.3 Manual Field Mapping

1. Upload PDF
   ↓
2. Extract fields
   ↓
3. Open Interactive Mapper
   ├─ Drag PDF fields to blueprint structure
   ├─ Search VADS patterns in real-time
   ├─ Assign UI/schema patterns
   └─ Configure conditional logic
   ↓
4. Generate with custom mapping

Use Case: Complex forms that need manual intervention

Time: 15-30 minutes

---

7. AI/ML Pipeline

7.1 Model Selection

Claude Opus 4.1 (Primary)

• Use Cases:
  • Plan generation
  • Field transformation
  • Page code generation
  • Code fixing
• Context: 200K tokens
• Output: 64K tokens
• Strengths: High-quality code, follows complex instructions

Claude Sonnet 4.5 (Secondary)

• Use Cases:
  • Pattern analysis (needs 1M context for large forms)
  • Import/export validation
  • Integration testing
• Context: 1M tokens (extended)
• Output: 64K tokens
• Strengths: Faster, cheaper, great for validation tasks

7.2 Prompt Engineering

Key Techniques:

1. Few-Shot Learning: Provide 2-3 gold standard examples
2. Chain of Thought: Break down complex tasks into steps
3. Structured Output: Use JSON schemas for validation
4. Negative Examples: Show what NOT to do
5. Empathic Instructions: Emphasize critical rules multiple times

Example Prompt Structure:

## CONTEXT
You are a VA.gov form generator...

## EXAMPLE (Follow this EXACTLY)
[Gold standard example]

## REQUIREMENTS
1. Use ONLY platform/forms-system patterns
2. NO vets-json-schema imports
3. Double quotes for all strings
...

## INPUT
[Extracted fields]

## OUTPUT FORMAT
Return ONLY valid JavaScript code. No markdown, no explanations.

7.3 Code Sanitization Pipeline

Stage 1: Quote Normalization

• Convert single quotes → double quotes (linter requirement)
• Fix mismatched quotes (e.g., "text' → "text")
• Convert straight apostrophes → curly apostrophes (U+2019) in user-facing text

Stage 2: Import Cleanup

• Remove vets-json-schema imports
• Fix platform import paths
• Remove test-data.json imports
• Remove hallucinated constants files

Stage 3: Structure Validation

• Ensure all pages are top-level (no nested paths)
• Validate array builder export names match arrayPath
• Check for signature pages (should be removed)

Stage 4: Pattern Validation

• Verify all UI patterns have matching schema patterns
• Check for deprecated patterns
• Validate conditional logic syntax

Implementation: /lib/page-generator.ts:26-96 (sanitizeGeneratedCode)

7.4 Hallucination Prevention

Common AI Hallucinations:

1. Importing non-existent test-data.json
2. Creating constants.js files that don't exist
3. Using vets-json-schema (simple forms don't use it)
4. Inventing new pattern names
5. Incorrect platform import paths

Prevention Strategies:

1. Explicit negative instructions ("DO NOT import test-data.json")
2. Provide exhaustive list of valid patterns
3. Show correct import paths in every example
4. Post-processing removal of hallucinated imports
5. Validation step catches and fixes

---

8. Integration Points

8.1 vets-website

Location: ../vets-website (default) or $VETS_WEBSITE_PATH

Integration Points:

1. Scaffold Output: Creates files in src/applications/simple-forms/{form-name}/
2. Gold Standard Search: Searches all src/applications/ for similar forms
3. Pattern Extraction: Extracts reusable patterns from existing forms
4. Testing: Can be tested in vets-website with yarn watch

Required Setup:

1. Clone vets-website: git clone https://github.com/department-of-veterans-affairs/vets-website.git
2. Set environment variable: VETS_WEBSITE_PATH=../vets-website
3. Install dependencies: cd vets-website && yarn install
4. Apply Node 22 patch (see README)

8.2 Anthropic API

Configuration:

• Set ANTHROPIC_API_KEY environment variable
• Get key from: https://console.anthropic.com/

Usage Patterns:

• Streaming for long operations (SSE)
• Batching for parallel page generation
• Retry logic with exponential backoff
• Cost tracking and token counting

Costs (Approximate):

• Small form (5 pages): $0.50-1.00
• Medium form (15 pages): $1.00-2.00
• Large form (30 pages): $2.00-3.00

8.3 VADS MCP Server

URL: https://vads-mcp.a6lab.ai/sse

Purpose: Real-time access to VA Design System patterns

Endpoints:

• /search - Search patterns by keyword
• /component - Get component details
• /patterns - List all patterns

Benefits:

• Up-to-date pattern documentation
• Accessibility guidelines
• Best practices from design.va.gov
• Real-time pattern examples

Implementation: /lib/mcp/vads-client.ts

8.4 Blueprint Library

Location: /blueprints/*.plan.json

Structure:

{
  "formNumber": "21P-530",
  "metadata": { "title": "...", "category": "..." },
  "chapters": [...],
  "pdfFieldMappings": {...}
}

Usage:

1. Auto-loaded by form number
2. Used for field-to-structure mapping
3. Speeds up generation significantly
4. Can be manually edited/extended

---

9. Code Generation

9.1 Generated File Structure

src/applications/simple-forms/{form-name}/
├── manifest.json               # App metadata
├── app-entry.jsx              # Webpack entry
├── routes.jsx                 # React Router config
├── sass/
│   └── {form-name}.scss      # Form styles
├── reducers/
│   └── index.js              # Redux store
├── containers/
│   ├── App.jsx               # Main container
│   ├── IntroductionPage.jsx  # Landing page
│   └── ConfirmationPage.jsx  # Submission confirmation
├── config/
│   ├── form.js               # Form configuration
│   ├── prefill-transformer.js # Data prefill
│   └── submit-transformer.js  # Submission transform
└── pages/
    ├── index.js              # Page barrel export
    ├── veteranInfo.js        # Example page
    ├── contactInfo.js        # Example page
    └── dependentsPages.js    # Array builder example

9.2 Page Templates

Regular Page:

import {
  titleUI,
  fullNameUI,
  fullNameSchema,
} from 'platform/forms-system/src/js/web-component-patterns';

export default {
  uiSchema: {
    ...titleUI('Page title'),
    fieldName: fullNameUI(),
  },
  schema: {
    type: 'object',
    properties: {
      fieldName: fullNameSchema,
    },
    required: ['fieldName'],
  },
};

Array Builder Page:

import { arrayBuilderPages } from 'platform/forms-system/src/js/patterns/array-builder';
import {
  arrayBuilderYesNoUI,
  arrayBuilderYesNoSchema,
  arrayBuilderItemFirstPageTitleUI,
  fullNameUI,
  fullNameSchema,
} from 'platform/forms-system/src/js/web-component-patterns';

const dependentsOptions = {
  arrayPath: 'dependents',
  nounSingular: 'dependent',
  nounPlural: 'dependents',
  required: true,
  maxItems: 10,
};

export const dependentsPages = arrayBuilderPages(
  dependentsOptions,
  pageBuilder => ({
    dependentsSummary: pageBuilder.summaryPage({
      title: 'Dependents',
      path: 'dependents',
      uiSchema: dependentsSummaryPage.uiSchema,
      schema: dependentsSummaryPage.schema,
    }),
    dependentsDetails: pageBuilder.itemPage({
      title: 'Dependent information',
      path: 'dependents/:index/details',
      uiSchema: dependentsDetailsPage.uiSchema,
      schema: dependentsDetailsPage.schema,
    }),
  })
);

Conditional Logic:

{
  uiSchema: {
    hasRemarried: yesNoUI('Have you remarried?'),
    spouseName: {
      ...fullNameUI('Spouse name'),
      'ui:options': {
        depends: formData => formData.hasRemarried === true
      }
    }
  }
}

9.3 Form Configuration

config/form.js Structure:

export default {
  formId: '21P-530',
  version: 0,
  prefillEnabled: true,
  savedFormMessages: {
    notFound: 'Please start over...',
    noAuth: 'Please sign in...',
  },
  title: 'Apply for burial benefits',
  subTitle: 'Form 21P-530',
  defaultDefinitions: {},
  chapters: {
    veteranInfo: {
      title: 'Veteran information',
      pages: {
        veteranDetails: {
          path: 'veteran-details',
          title: 'Veteran details',
          uiSchema: veteranDetailsPage.uiSchema,
          schema: veteranDetailsPage.schema,
        }
      }
    }
  }
};

---

10. Verification System

10.1 Verification Categories (9 Total)

1. Syntax & Quote Style

• Unterminated strings
• Mixed quotes (must be double quotes)
• Quotes after JSX tags

2. Import Paths

• Correct platform imports (platform/startup, platform/polyfills)
• Sass imports present
• No hallucinated imports

3. Required Configuration

• preSubmitInfo present
• v3SegmentedProgressBar: true
• footerContent imported
• transformForSubmit configured
• prefillTransformer configured

4. No Hallucinated Imports

• No test-data.json
• No constants.js
• No vets-json-schema

5. File Structure

• All required files present
• Proper directory organization

6. Depends Logic

• Proper formatting of depends functions
• Optional chaining (?.) usage
• Strict equality (===) checks

7. Sass Imports

• CSS library variables
• Form process module
• Schemaform styles
• Form confirmation styles

8. Page Imports/Exports

• pages/index.js exists
• All imported pages exported
• Barrel export pattern correct

9. PDF Accuracy

• All PDF fields represented
• Array builders match PDF structure
• Conditional logic preserved

10.2 Auto-Fix Capabilities

Automatic Fixes:

• Remove vets-json-schema imports → Replace with platform imports
• Fix platform import paths → Correct to platform/startup etc.
• Remove test-data.json imports → Delete lines
• Remove constants imports → Delete lines
• Add missing sass imports → Append to sass file
• Add missing required imports → Add to file

Manual Review Required:

• Complex conditional logic errors
• Incorrect page structure
• Missing PDF fields
• Incorrect array builder configuration

10.3 Verification API

POST /api/pages/verify

Input:

{
  "formPath": "/path/to/form",
  "formNumber": "21P-530"
}

Output:

{
  "success": false,
  "issues": [
    {
      "category": "import-paths",
      "severity": "error",
      "message": "Invalid import: vets-json-schema",
      "file": "config/form.js",
      "line": 12,
      "autoFixable": true
    }
  ],
  "stats": {
    "totalIssues": 5,
    "errors": 2,
    "warnings": 3,
    "autoFixable": 4
  }
}

---

11. Performance & Scalability

11.1 Generation Performance

Form Size	Single-Agent	Multi-Agent	Speedup
5 pages	3-4 min	45-60 sec	4x
15 pages	7-10 min	90-120 sec	5x
25 pages	12-15 min	2-3 min	5-6x
40 pages	20+ min	3-4 min	6x

11.2 Scalability Limits

Current Limits:

• PDF Size: 50MB max (configurable)
• Form Complexity: Up to 50 pages (tested)
• Concurrent Jobs: 10 simultaneous uploads
• Storage: 24-hour job retention
• AI Context: 200K tokens (Opus), 1M tokens (Sonnet)

Bottlenecks:

1. AI API rate limits (Anthropic tier-based)
2. File I/O for large forms
3. pdftk processing time for complex PDFs

Optimization Strategies:

1. Parallel page generation (already implemented)
2. Caching of gold standard searches
3. Blueprint pre-loading for known forms
4. Streaming responses for long operations

11.3 Cost Analysis

Per-Form Costs (USD):

Form Size	Tokens Used	API Cost	Time
Small (5p)	~50K	$0.50	1 min
Medium (15p)	~150K	$1.50	2 min
Large (30p)	~300K	$3.00	3 min

Cost Breakdown:

• Structure Planning: 20%
• Page Generation: 60%
• Validation/Testing: 20%

Monthly Costs (Example):

• 10 forms/day × 30 days = 300 forms/month
• Average cost: $1.50/form
• Total: $450/month

---

12. Security & Privacy

12.1 Data Handling

PDF Processing:

• PDFs stored temporarily in /temp/pdfs/
• Auto-deleted after 24 hours
• Not uploaded to external servers (except Anthropic API)

Extracted Data:

• Field names and metadata sent to Anthropic API
• Field values NOT sent (only structure)
• No PII processed or stored

Generated Code:

• Stored locally in vets-website
• Not transmitted to external services
• Committed to version control as needed

12.2 API Security

Anthropic API:

• API key stored in environment variable
• Not exposed to frontend
• All calls server-side only

VADS MCP Server:

• Public API, no authentication required
• Read-only access to design system docs
• No sensitive data transmitted

12.3 Access Control

Current State:

• No authentication (local development tool)
• All features available to localhost
• No multi-tenancy

Production Recommendations:

• Add OAuth/SAML authentication
• Role-based access control
• Audit logging for generated code
• Rate limiting per user

---

Appendix A: Environment Variables

# Required
ANTHROPIC_API_KEY=sk-ant-...        # Anthropic API key

# Optional
VETS_WEBSITE_PATH=../vets-website   # Path to vets-website repo
CONTENT_BUILD_PATH=../content-build # Path to content-build repo (optional)
NODE_ENV=development                # Environment (development, production)

Appendix B: Common Issues

Issue: pdftk not found Solution: brew install pdftk-java (Mac) or apt-get install pdftk (Linux)

Issue: Native Yeoman fails Solution: Fallback generator runs automatically, no action needed

Issue: AI generates incorrect imports Solution: Verification system auto-fixes most import issues

Issue: Form number not detected Solution: Manually enter form number in Yeoman config step

Issue: Gold standards not found Solution: Check VETS_WEBSITE_PATH environment variable

Appendix C: Development Commands

# Development
npm run dev              # Start dev server (port 5005)
npm run build            # Build for production
npm run start            # Start production server
npm run lint             # Run ESLint

# Testing
npm run test             # Run all tests
npm run test:watch       # Watch mode
npm run test:coverage    # Generate coverage report
npm run test:integration # Integration tests only
npm run test:unit        # Unit tests only

# Utilities
npm run analyze:tokens   # Analyze AI token usage
./scripts/test-scaffold.sh FORM-NUMBER  # Test scaffold generation

---

Last Updated: November 19, 2025 Version: 2.0.0 (Multi-Agent) Author: @amponce / agile6