API Specification Regeneration Rule

CRITICAL: After ANY changes to api.yml, TypeScript interfaces MUST be regenerated before proceeding to implementation.

The Rule

After completing api.yml changes (before moving to code work), ALWAYS run:

npm run clean && npm run generate

Why Both Commands?

1. npm run clean - Removes leftover generated files that might cause conflicts
2. npm run generate - Generates fresh TypeScript interfaces from api.yml

WHY: Without clean, old generated files may remain and cause:

• Type conflicts
• Import errors
• Stale interfaces that don't match current api.yml

When to Run

✅ MUST Run

1. After api.yml edits - Before implementing operations
2. After schema changes - Before writing mappers
3. After parameter changes - Before updating client code
4. After operation additions - Before creating producer methods
5. Before Gate 2 validation - To validate types generate correctly

❌ Don't Need to Run

• During active api.yml editing (only after final change)
• If you're just reading api.yml
• During planning phase (before any code work)

Multiple api.yml Changes

If making multiple changes to api.yml:

# Edit api.yml multiple times
# ... change 1 ...
# ... change 2 ...
# ... change 3 ...

# THEN run generation ONCE after all changes complete
npm run clean && npm run generate

Don't regenerate after each individual change - only after the last change before moving to implementation.

In Workflows

Standard Pattern in All Workflows

Whenever a workflow mentions type generation or working with generated types:

# ✅ CORRECT - Always use clean + generate
npm run clean && npm run generate

# ❌ WRONG - Missing clean
npm run generate

Gate 2: Type Generation

Gate 2 specifically validates that types generate correctly:

# Gate 2 validation
npm run clean && npm run generate

# Check for errors
echo $?  # Should be 0 (success)

If generation fails, api.yml has errors that must be fixed before proceeding.

Error Handling

If npm run clean && npm run generate fails:

1. Read the error message - TypeScript/OpenAPI errors point to specific issues
2. Fix api.yml - Address the schema/type error indicated
3. Run again - npm run clean && npm run generate
4. Repeat until successful

Common errors:

• Missing required fields
• Invalid $ref references
• Circular dependencies
• Invalid OpenAPI syntax

Validation After Generation

After successful generation, check:

# 1. Generation succeeded
npm run clean && npm run generate
echo $?  # Should be 0

# 2. Check generated files exist
ls -la src/gen/

# 3. Look for type errors in project
npm run build  # Should compile without errors

In Agent Instructions

Agents working on api.yml or implementation should:

1. Complete api.yml changes
2. Run: npm run clean && npm run generate
3. Verify: Check exit code and generated files
4. Proceed: Only if generation successful

Example Workflow

# 1. Make api.yml changes
# ... edit api.yml ...

# 2. Regenerate types (with clean)
npm run clean && npm run generate

# 3. Verify successful
if [ $? -eq 0 ]; then
  echo "✅ Types generated successfully"
  # Proceed to implementation
else
  echo "❌ Generation failed - fix api.yml"
  # Fix errors and retry
fi

References

• Gate 2 Validation: @.claude/rules/gate-2-type-generation.md
• API Spec Rules: @.claude/rules/api-specification-critical-12-rules.md
• Build Validation: @.claude/rules/gate-6-build.md

REMEMBER: npm run clean && npm run generate not just npm run generate - clean prevents leftover conflicts.