VibesPro Generator Handbook Epic

User Journey

The VibesPro Generator bounded context provides the Nx-based generator infrastructure for spec-to-code projections. It enables library generation, meta-generators, type sync, pattern oracles, and governance hooks to transform SEA™ DSL specifications into executable code.

Jobs to be Done & EARS Requirements

Job: Generate Nx Library

User Story: As a developer, I want to generate a TypeScript library using Nx generators, so that I can quickly scaffold code with proper structure and configuration.

EARS Requirement:

• While generating libraries, when pnpm exec nx g @nx/js:library is executed, the VibesPro generator context shall:
  1. Accept generator parameters:
     • Library name (e.g., my-utils)
     • Directory path (--directory=libs/shared)
     • Bundler (--bundler=tsc|vite|esbuild)
     • Unit test runner (--unitTestRunner=jest|vitest)
  2. Generate Library Structure:
     • Create libs/shared/my-utils/src/index.ts
     • Create libs/shared/my-utils/src/lib/my-utils.ts
     • Create libs/shared/my-utils/package.json
     • Create libs/shared/my-utils/tsconfig.json
     • Create libs/shared/my-utils/tsconfig.lib.json
     • Create libs/shared/my-utils/jest.config.ts (if Jest selected)
  3. Configure Nx Integration:
     • Update nx.json with new project
     • Set up implicit dependencies
     • Configure build targets
  4. Return success message with created files list

Job: List Available Generators

User Story: As a developer, I want to discover available Nx generators, so that I can find the right generator for my task.

EARS Requirement:

• While exploring generators, when pnpm exec nx list is executed, the VibesPro generator context shall:
  1. Query installed Nx plugins and their generators
  2. Return generator list with:
     • Generator name (e.g., @nx/js:library)
     • Plugin name (e.g., @nx/js)
     • Description of generator purpose
     • Available aliases (if any)
  3. Support filtering by plugin:
     • pnpm exec nx list @nx/js → show only js plugin generators
     • pnpm exec nx list @nx/react → show only react plugin generators
  4. Display help command for each generator

Job: Preview Generator Output

User Story: As a developer, I want to preview generator output before writing files, so that I can verify the generator will produce what I expect.

EARS Requirement:

• While generating code, when --dry-run flag is specified, the VibesPro generator context shall:
  1. Execute generator with all parameters
  2. Calculate what files would be created
  3. Display file list without writing to disk
  4. Show file contents (if verbose mode enabled)
  5. Return success with dry-run confirmation

Job: Create Custom Generator

User Story: As a platform engineer, I want to create a custom Nx generator for organization-specific patterns, so that teams can generate consistent code structures.

EARS Requirement:

• While authoring generators, when just generator-new my-generator --type=custom is executed, the VibesPro generator context shall:
  1. Create Generator Skeleton:
     • Generate generator files in generators/my-generator/
     • Create schema.json with generator options
     • Create generator.ts with run() function
     • Create README.md with usage documentation
  2. Configure Generator:
     • Set generator name and description
     • Define input schema (options, required fields)
     • Set up file generation templates
  3. Register Generator:
     • Add to nx.json generators collection
     • Enable discovery via nx list
  4. Return generator location and usage instructions

Job: Sync Types from SEA DSL

User Story: As a developer, I want to generate TypeScript types from SEA™ DSL specifications, so that my code matches the domain model.

EARS Requirement:

• While syncing types, when type sync is executed, the VibesPro generator context shall:
  1. Parse SEA™ DSL files
  2. Extract Type Definitions:
     • Entities → TypeScript interfaces
     • Resources → TypeScript type with unit
     • Flows → Command/Query/Event types
     • Policies → Validation functions
  3. Generate Type Files:
     • Create .types.ts files in appropriate lib directories
     • Export interfaces, types, and enums
     • Add JSDoc comments from SEA™ DSL documentation
  4. Validate Generated Types:
     • Ensure no duplicate type names
     • Verify type references are valid
     • Check circular dependencies
  5. Return generated type files with locations

Job: Apply Pattern Oracle

User Story: As a developer, I want to use Pattern Oracle to suggest code patterns based on SEA™ DSL context, so that I generate code following best practices.

EARS Requirement:

• While generating code, when Pattern Oracle is consulted, the VibesPro generator context shall:
  1. Analyze Context:
     • Parse SEA™ DSL specification
     • Identify domain patterns (CQRS, event sourcing, etc.)
     • Extract bounded context and layer information
  2. Match Patterns:
     • Query pattern library for matching contexts
     • Retrieve pattern templates (repository, service, factory, etc.)
     • Select appropriate pattern based on annotations
  3. Generate Code:
     • Apply pattern template to specific entity/flow
     • Fill placeholders with domain-specific names
     • Include best practices from pattern oracle
  4. Return generated code with pattern references

Job: Execute Governance Hooks

User Story: As a governance officer, I want to validate generated code against governance policies, so that all code complies with architectural rules.

EARS Requirement:

• While generating code, when governance hooks are triggered, the VibesPro generator context shall:
  1. Pre-Generation Hook:
     • Validate SEA™ DSL spec against governance policies
     • Check for authorized patterns and annotations
     • Block generation if spec violates policies
  2. Post-Generation Hook:
     • Validate generated code against CALM rules
     • Check layer boundary compliance
     • Verify dependency constraints
     • Run linting and formatting checks
  3. Handle Violations:
     • Report violations with specific file locations
     • Suggest remediation for governance issues
     • Block commit if critical violations found
  4. Return Governance Status (pass/fail) with report

Job: Configure Meta-Generators

User Story: As a platform engineer, I want to create meta-generators that orchestrate multiple generators, so that I can generate complex multi-file structures with a single command.

EARS Requirement:

• While configuring meta-generators, when meta-generator is defined, the VibesPro generator context shall:
  1. Define Meta-Generator:
     • Specify orchestrating generator
     • Define sequence of sub-generators to execute
     • Configure parameters passing between generators
  2. Execute Meta-Generator:
     • Run each sub-generator in sequence
     • Pass outputs from one generator as inputs to next
     • Aggregate all generated files
  3. Handle Errors:
     • Rollback all generators if any fails
     • Report error with specific generator in sequence
     • Support partial generation with explicit confirmation
  4. Return aggregated result with all generated files

Domain Entities Summary

Root Aggregates

• NxGenerator: Nx generator with schema, options, templates, and run() function
• GeneratorOutput: Generated code artifacts with file paths, content, and metadata
• TypeSyncResult: TypeScript type generation from SEA™ DSL with type definitions and file locations
• PatternApplication: Pattern oracle match with pattern ID, template, and generated code

Value Objects

• GeneratorSchema: JSON schema defining generator options and validation rules
• DryRunResult: Preview of generator output with file list and contents
• GovernanceReport: Pre/post-generation validation results with violations and status
• MetaGeneratorSequence: Ordered list of generators with parameter mappings

Policy Rules

• DryRunDefault: Generators should support –dry-run for safe preview
• TypeSyncRequired: All code must use types synced from SEA™ DSL
• GovernanceFirst: All generation must pass governance hooks before writing files
• NxWorkspaceIntegrity: Generated code must conform to Nx workspace rules

Integration Points

• Nx CLI: Generator execution via pnpm exec nx g <generator>
• just recipes: Task runner shortcuts for common generator operations
• Type Sync: Python script for SEA™ DSL to TypeScript type generation
• Pattern Oracle: Pattern library for best practice code generation
• Governance Hooks: Pre/post-generation validation against CALM and SEA™ policies

Success Metrics

• Generator Success Rate: >99% of generations complete without errors
• Type Sync Accuracy: 100% of SEA™ DSL types reflected in generated TypeScript
• Governance Pass Rate: >95% of generations pass governance validation on first try
• Generator Speed: <5 seconds for typical library generation

Non-Functional Requirements

• NFR-001: All generators support –dry-run for safe preview
• NFR-002: Generated code is formatted and linted before write
• NFR-003: Meta-generators provide atomic all-or-nothing generation
• NFR-004: Generator templates are version-controlled with the codebase