3yearplan/CLAUDE.md

Project Context

This directory contains a 3-year plan for transforming and enhancing SCADA IT/OT interfaces and data collection.

Work in this repo focuses on planning, designing, and tracking the multi-year roadmap for modernizing shopfloor systems — bridging IT and OT layers, improving operator interfaces, and upgrading data collection pipelines.

Structure

Plan content lives in markdown files at the repo root to keep it easy to read and update:

• current-state.md — snapshot of today's SCADA IT/OT systems, integrations, data collection, and pain points.
• goal-state.md — target end-state at the close of the 3-year plan, including success criteria.
• roadmap.md — migration plan / sequencing from current state to goal state over the 3 years.
• status.md — working-session bookmark; records where we left off and the top pending items. Not authoritative plan content.

Component detail files

• current-state/legacy-integrations.md — authoritative inventory of bespoke IT↔OT integrations that cross ScadaBridge-central outside ScadaBridge. Denominator for pillar 3 retirement.
• schemas/ — Canonical OT equipment definitions seed (temporary location — see schemas/README.md). JSON Schema format definitions, FANUC CNC pilot equipment class, UNS subtree example, and documentation. Contributed by the OtOpcUa team; ownership TBD. To be migrated to a dedicated schemas repo once created.

Output generation pipeline

• outputs/ — repeatable PPTX + PDF generation over the plan markdown. Entry point: outputs/README.md (trigger phrases + regeneration checklist). Structure anchors: outputs/presentation-spec.md for the 16-slide mixed-stakeholder deck and outputs/longform-spec.md for the faithful-typeset long-form PDF. Outputs live under outputs/generated/; do not hand-edit them.
• templates/ — clean Zimmer Biomet PowerPoint template extracted from example_powerpoint.pptx: cover slide + content-with-bottom-border layout. See templates/README.md for design specs and how to use; rebuild via python3 templates/build_template.py.

Quick reference — regenerating outputs:

• regenerate presentation — rebuilds the 16-slide PPTX from current plan source files per outputs/presentation-spec.md
• regenerate longform — rebuilds the PDF per outputs/longform-spec.md (not yet run)
• regenerate outputs — both
• To change slide structure: edit outputs/presentation-spec.md, then regenerate. Don't edit the PPTX directly.
• To change content: edit the source plan files (current-state.md, goal-state.md, roadmap.md, etc.) — the next regeneration picks up changes automatically.
• Workspace: outputs/workspace/ contains the HTML slides and generation JS script from the last run.

As the plan grows, add further markdown files and link them from here.

Breaking out components

Individual components (a system, an interface, a data pipeline, an initiative) often need more detail than fits inline. When a section in current-state.md or goal-state.md outgrows a few paragraphs:

1. Create a dedicated file under a topical subdirectory, e.g.:
   • current-state/<component>.md
   • goal-state/<component>.md
   • components/<component>.md (when it spans both states)
2. Leave a short summary in the parent file and link to the detail file.
3. Keep filenames lowercase-kebab-case so they're easy to reference.

Conventions

• Keep everything in markdown — no proprietary formats.
• Prefer editing existing files over adding new ones; split a file only when it gets unwieldy or when a component needs its own detail page (see above).
• Use _TBD_ placeholders for sections that aren't yet filled in, so gaps stay visible.