React Flow Repair, Migration, And Build Protocol

Execute this protocol in order. Keep fixes small, reversible, and validated.

Required Outputs

1. Produce a short audit report of the current React Flow architecture.
2. Produce a prioritized fix list with risk and expected impact.
3. Apply safe fixes in small patches when requested.
4. Generate missing typed scaffolding when the project is incomplete.
5. Report verification results and any residual risks.

Workflow

1. Discover project shape.
   • Locate all React Flow usage (ReactFlow, useNodesState, useEdgesState, addEdge, custom node/edge components).
   • Confirm framework/runtime details (vite, next, TypeScript config, lint setup).
2. Validate graph model contracts.
   • Centralize Node and Edge type definitions.
   • Validate id strategy, data schema stability, and custom type names.
3. Validate state and event wiring.
   • Ensure onNodesChange, onEdgesChange, and onConnect are correctly bound.
   • Detect duplicated or conflicting state sources.
4. Validate rendering and performance.
   • Keep nodeTypes and edgeTypes references stable.
   • Detect avoidable re-renders and unsafe inline object creation in hot paths.
5. Apply auto-fixes.
   • Apply highest-impact, low-risk fixes first.
   • Preserve behavior unless an explicit bug fix requires a behavior change.
   • Include migration notes for any public API or schema changes.
6. Run migration pass when legacy APIs are present.
   • Detect legacy package/import usage and map to modern @xyflow/react.
   • Migrate types first, then runtime wiring, then persistence compatibility.
   • Add migration guard for old payload versions when needed.
7. Scaffold from scratch when needed.
   • Generate a minimal typed baseline with custom node support and layout helper.
   • Ensure resulting scaffold compiles in a standard TS React setup.
8. Verify.
   • Run available tests or static checks.
   • If checks are missing, provide manual verification steps.

Guardrails

• Preserve existing business logic unless the bug requires change.
• Keep node and edge ids stable across operations and persistence cycles.
• Avoid introducing a second state manager unless explicitly requested.
• Keep templates framework-agnostic unless the repository enforces a framework.
• Prefer typed interfaces over any for flow data payloads.

References

• Use references/CHECKLIST.md for systematic auditing.
• Use references/FIX_PATTERNS.md for common issue-to-fix mapping.
• Use references/EXAMPLES.md for prompt and output patterns.
• Use references/MIGRATION_CHECKLIST.md and references/API_RENAMES.md for upgrade work.
• Use references/MIGRATION_EXAMPLES.md for migration request patterns.

Templates

• Start from templates/Flow.tsx.tmpl for baseline flow container.
• Start from templates/nodeTypes.tsx.tmpl and templates/edgeTypes.tsx.tmpl for typed registries.
• Use templates/layout.ts.tmpl for deterministic starter layout behavior.
• Use templates/migration-plan.md.tmpl for patch-by-patch upgrade planning.
• Use templates/compat-adapter.ts.tmpl when backward compatibility is required.