Quartz 4

08 - AI Integration

3 min read

AI Integration

VizzyCode integrates with multiple headless AI tools and provides guidance for giving AI agents enough context to repair Vizzy missions without damaging fidelity-sensitive regions. ia prompts

Do not provide only the .cs file

A .vizzy.cs file alone is insufficient context for mission repair. Include the project docs, validator state, original XML when available, sidecar metadata, and bridge reports when craft-specific behavior matters.

Providers

ProviderCLI commandDefault modelInteractive mode
Claudeclaude -p --verbose --output-format stream-json --include-partial-messagesConfigured by Claude CLIHeadless stream JSON plus optional UI integration
Geminigemini headless binarygemini-2.5-proHeadless command execution
OpenAI/Codexcodex exec --jsongpt-5-codexJSON execution mode
OpenCodeopencode run --format jsonProvider configurationSupports custom Base URL

Settings file:

%AppData%\VizzyCode\ai-settings.json

AI Flow

flowchart LR
    A[User request] --> B{Mode}
    B -->|Headless| C[Build context bundle]
    B -->|Interactive| D[Open chat panel]
    C --> E[Run provider CLI]
    D --> E
    E --> F[Patch .vizzy.cs or docs]
    F --> G[Export]
    G --> H[Validate]
    H --> I[Roundtrip or Juno test]

Context Bundles

Minimum bundle for normal authoring

  1. README.md
  2. docs/VizzyAuthoringGuide.md
  3. docs/VizzyBlocksMegaGuide.md
  4. docs/ExportValidationAndCoverageGuide.md
  5. Current .vizzy.cs file

Minimum bundle for AI repair

  1. README.md
  2. docs/VizzyAuthoringGuide.md
  3. docs/VizzyBlocksMegaGuide.md
  4. docs/AiRepairContextGuide.md
  5. docs/RawPreservationGuide.md
  6. docs/ExportValidationAndCoverageGuide.md
  7. Current .vizzy.cs
  8. Current validator output

Complete fidelity-sensitive bundle

  1. Original working XML
  2. Current .vizzy.cs
  3. Current exported XML if it exists
  4. Matching .vizzy.meta.json sidecar
  5. Raw fragment decode output for any unclear Raw* payloads
  6. CLI export output
  7. VS Code export output if tool parity is being checked
  8. Craft snapshot report if part names, stages, mass, fuel, or activation groups matter
  9. Telemetry report if runtime state matters

Reports first

Prefer bridge-generated Markdown reports for AI context, then include JSON only when exact raw fields are needed.

Repair Rules For AI

RuleReason
Determine source of truth first.Original XML and current code can diverge.
Check whether the region has VZTOPBLOCK, VZBLOCK, or VZEL.Anchors indicate preserved imported structure.
Do not rewrite raw fragments blindly.RawXml* often marks an exact XML boundary.
Fix one structural issue at a time.Juno load failures can stack.
Run export validation after every change.Validator catches known invalid shapes.

Prompt Template

Investigate this Vizzy mission without globally rewriting it.
 
First determine whether the original XML or the current .vizzy.cs is the source of truth.
Then identify whether the failing region is preserved imported XML or handwritten authoring code.
If the region has VZTOPBLOCK, VZBLOCK, VZEL, RawXml*, or a sidecar entry, treat that as a fidelity boundary unless proven otherwise.
Run export validation and fix one exact XML structural issue at a time.
Do not replace raw-preserved fragments only for readability.

Related notes: 02 - Conversion Engine (VizzyXmlConverter), 04 - Export Validation, 05 - Raw Preservation, 06 - Juno Live Bridge, 10 - Vizzy Authoring Guide, 14 - Troubleshooting.

Graph View

Backlinks