Rungstone

View saved version →

---
name: rungstone-hmi-scada
description: Understand, retarget, migrate, verify and clean up HMI and SCADA projects alongside the PLC code they talk to. Use this skill whenever the user mentions an HMI, SCADA, Ignition, FactoryTalk View, PanelView, WinCC, Wonderware/AVEVA, operator screens, faceplates, HMI tags or tag databases, alarm lists, alarm floods, nuisance or chattering alarms, alarm history, ISA-18.2, or wants to move screens, tags, scripts or alarms to a new PLC or a new HMI platform - even if they only say "the screens" or "the panel" or paste a tag CSV.
---

> In this skill, `<skill-dir>` means the folder that contains this SKILL.md. Run its scripts with `python3 <skill-dir>/scripts/...` from the user's project folder.

# Rungstone - HMI/SCADA

Rungstone works on **exported files** from HMI/SCADA projects (FactoryTalk View ME/SE, Ignition, WinCC) and
connects them to the PLC project analysed by the sibling skill `rungstone-plc`.

## Non-negotiable rules

1. **Read-only.** Never connect to or write to a running controller, HMI, SCADA server, OPC server or
   historian. Outputs are files the engineer imports into the vendor tool. Do not offer to "push",
   "deploy" or "download" anything. This includes writing scripts or commands for the user to run against live equipment: decline, and point to the vendor IDE and the site's change procedure.
2. **Safety-rated logic is excluded from every workflow** (e-stops, safety relays, Siemens F-blocks,
   GuardLogix safety tasks). When the PLC project contains it, show the notice from the PLC skill's
   `excluded_safety` list. HMI objects bound to safety-flagged tags are listed but never retargeted
   silently; an HMI **write** to a safety tag is always a high conflict.
3. **Never claim behavior was verified unless a simulation actually ran.** Label every result
   "simulated, not hardware-tested". If nothing ran, say "scenario plan only - not run".
4. **Label every meaning** as `confirmed`, `comment` (caption/description/PLC comment), `io_map`, `inferred`
   (say from what) or `unknown`. Never present a guess as fact. Position-based label association is inferred.
5. **The engineer approves every flagged change before export.** Retarget/migrate output is a draft; review
   items go into `.rungstone/review_queue.json`.
6. **Show scope and a cost estimate before any large job** (more than ~20 screens, ~2,000 tags, or alarm
   history above ~50 MB): count files/objects with `parse_hmi.py` first, give the estimate (use
   `rungstone-plc/scripts/estimate.py` for the PLC side) and wait for the go-ahead.
7. **Parse only.** Customer scripts (VBScript, VBA, Python/Jython, JavaScript) are read as text and never
   executed. XML goes through the safe parser (defusedxml or equivalent: no DTDs/entities). **Never open, decrypt or work around source protection or know-how protection, and never explain how to:** report a protected routine or block as "cannot be read" and stop there.

## Scripts

All in `<skill-dir>/scripts/`, Python 3.9+, standard library (openpyxl optional for .xlsx). Each
prints compact JSON; add `--md file` for a Markdown report. Run them; do not paste raw exports into context.

| Script | Use for |
|---|---|
| `parse_hmi.py FILES_OR_DIRS -o inv.json` | Inventory: screens -> objects (type, label, bindings, actions), scripts (reads/writes/side effects), alarms, tags, aggregated PLC references |
| `verify_bindings.py --hmi ... --plc ... [--target T] [--simulate] --md v.md` | Every binding resolves? + full PLC/HMI/SCADA consistency check; optional scenarios through the simulator |
| `retarget.py --mapping mapping.csv --hmi ... --out DIR [--device OLD=NEW] --md r.md` | Rebind HMI files to the translated PLC; writes copies, never originals; review items to the queue |
| `migrate_tags.py --hmi ... --to ignition-json\|wincc-csv\|factorytalk-csv --out DIR [--mapping ...] [--screens]` | Tag DB + alarms to another platform (DRAFT_* files), script stubs, screen wireframes |
| `alarm_analysis.py history.csv --md a.md [--operators N]` | ISA-18.2 KPIs, chattering/fleeting/stale/flood/consequential, bad actors, priority suggestions |

PLC side: when the user supplies the PLC project, these scripts use the sibling skill at
`<skill-dir>/../rungstone-plc/scripts` (parse_project.py, dependency_map.py, simulate.py). If that
folder is missing, say the `rungstone-plc` skill is needed for PLC resolution and fall back to a
`.rungstone/tagmap.json` (`verify_bindings.py --tagmap`) or HMI-only analysis.

## Project state

Shared with the other Rungstone skills in `.rungstone/` in the project folder (plain files, git friendly):
`mapping.csv` (old -> new, produced by rungstone-plc Translate) drives Retarget and Migrate;
`tagmap.json` holds signal meanings with their basis; `review_queue.json` gets every rebind that needs
judgement; `verify_results.json` gets simulation runs; `decisions.log` is the audit trail.
`<skill-dir>/scripts/_shared/state.py` manages it (`state.py status`, `state.py queue list --open`,
`state.py queue approve R3`). If `.rungstone/` does not exist and the work produces review items, run
`state.py init` first, then `state.py source FILE ...` for each HMI/SCADA export you read.

If `.rungstone/` exists, save the full answer you showed as `.rungstone/reports/hmi-<subject>.md`
(or `alarms-<subject>.md` for alarm cleanup), overwriting on a rerun, so the workbench's HMI/SCADA
tab shows it, and record generated tag or alarm databases with `state.py output FILE --workflow hmi`.

## Which reference to read

| Situation | Read |
|---|---|
| FactoryTalk View / PanelView files | `references/factorytalk-view.md` |
| Ignition tags, views, scripts, alarm journal | `references/ignition.md` |
| WinCC (TIA panels, Unified, V7/V8) | `references/wincc.md` |
| Alarm cleanup, priorities, response text | `references/alarm-management.md` |
| Writing any deliverable | `references/output-formats.md` (exact formats) |

## Workflow 1 - Understand HMI/SCADA

1. `parse_hmi.py <files> -o inv.json`. Read the JSON, not the raw exports.
2. If the PLC project is available, run `verify_bindings.py --hmi ... --plc ...` so you know what each tag
   really does in logic (use the PLC skill's dependency map for "who else writes it").
3. Write the deliverable in the Understand format: summary, per-screen object table (what each button and
   indicator does, PLC tag, basis), scripts in plain English (triggers, reads, writes, side effects like
   database writes), alarm list, open questions. Momentary buttons: say what happens if the operator holds it
   or comms drop. Multistate captions are the operator's meaning of each value - compare them with the PLC.

## Workflow 2 - Retarget (rebind to the translated PLC)

1. Needs `mapping.csv` from rungstone-plc Translate (columns `old_address, old_symbol, ..., old_type,
   new_symbol, new_address, new_type, basis, notes`, or a simple `old,new`). If it does not exist, say so and
   offer to run Translate or build the mapping first.
2. `retarget.py --mapping .rungstone/mapping.csv --hmi <files> --out rebound/ --target <t> [--device OLD=NEW]`.
3. Report rebinds, everything unmapped (do not guess a target for those), manual edits (script strings that
   need quoting changes), and the review items added. Timer/counter members are rebound by meaning
   (e.g. `.ACC` -> a new DINT tag, because IEC `ET` is TIME; `.DN` -> `.Q`) and always reviewed.
4. Remind: import the rebound copies into a test copy of the HMI project; nothing is final until approved.

## Workflow 3 - Migrate to another platform

1. `migrate_tags.py --hmi <files> --to <target> --out migrated/ [--mapping ...] [--screens]`.
2. Tag database and alarms come out as `DRAFT_*` files; scripts as stubs with the original code and the
   references they touch - port them with the user, explaining each change; screens only as
   **draft layout descriptions** (Markdown + HTML wireframe). Say clearly that screens are not migrated.
3. Flag inferred data types, priority remaps, driver address syntax, and WinCC's Word-bit trigger rule.

## Workflow 4 - Verify bindings

1. `verify_bindings.py --hmi ... --plc ... --md v.md` -> every binding resolved / broken / member_invalid /
   not_plc, plus conflicts.
2. With a PLC program: `--simulate` builds button, indicator and alarm scenarios and runs them through
   `rungstone-plc/scripts/simulate.py`. Report each as `ran` or `not run` with the reason (broken binding,
   unsupported instruction, simulator missing). Label: **simulated, not hardware-tested**.

## Workflow 5 - Consistency check across PLC + HMI + SCADA

Run `verify_bindings.py` with every HMI and SCADA export plus the PLC project (and `--target` if a
migration is planned). Report label mismatches (HMI caption vs PLC comment vs I/O map - contradictions such
as high/low or open/closed are high severity), broken links, competing writers (HMI writes a tag the PLC
also drives), read-never-written tags, HMI writes to inputs/read-only/safety tags, and members that change
meaning after translation (e.g. Timer `.ACC` has no direct IEC equivalent - propose the HMI rebind to a new
DINT tag). Put each finding in the conflicts table with evidence, then open questions.

## Workflow 6 - Alarm cleanup from alarm history

1. `alarm_analysis.py history.csv --md alarms.md [--operators N]` (ask how many operator positions share
   the alarms; default 1).
2. Report KPIs against ISA-18.2 guidance, nuisance alarms (chattering, fleeting) with evidence, floods with
   their driver (one chattering alarm vs a cascade), consequential pairs, standing alarms, bad actors.
3. Suggest priorities from consequence and time to respond using the matrix in
   `references/alarm-management.md`, and draft operator response text. With the PLC project, cite the logic
   that raises each alarm (rung/line) as the cause. Everything is a **suggestion for the alarm philosophy
   owner to approve** - mark inferred causes as inferred. Safety-related alarms: list for the safety team,
   do not re-prioritize.

## Limits

- Display formats are read from exports; binary-only sources (FactoryTalk `.MER`, WinCC V7 `.PDL`) cannot be
  parsed - ask for an export or screenshots plus object lists.
- Generic XML (Vision windows, WinCC Openness screens) is scanned for references; object roles are inferred.
- Scripts are never executed; their behavior is described from reading them.
- No live monitoring; this version analyses exported files only.

Referenced files: 25 — file references are metadata, not package contents.

View saved version →

---
name: rungstone-ops
description: Offline operations troubleshooting for industrial plants from exported data - why a line, machine, pump, conveyor or compressor stopped or tripped, downtime and stop causes, alarm and event logs, historian trends, first-out analysis, shift reports, MTBF/MTTR/availability, recurring faults. Use this whenever the user asks why something stopped, tripped, faulted or went down, asks about downtime, alarms, trends, historian or SCADA data, shift or downtime reports, or uploads historian/alarm/event CSV exports (PI, Ignition, FactoryTalk, WinCC) - even if they do not say "troubleshoot". Ties the data back to the PLC logic that caused the stop. Part of Rungstone; offline only, no live monitoring.
---

> In this skill, `<skill-dir>` means the folder that contains this SKILL.md. Run its scripts with `python3 <skill-dir>/scripts/...` from the user's project folder.

# Rungstone - Operations (offline troubleshooting)

Find out why equipment stopped, what the data shows around it, and which PLC logic
turned that condition into a stop - from **exported files only**.

## Non-negotiable rules

1. **Read-only and offline.** Never connect to, query, or write to a controller, HMI, SCADA
   server or historian. Work only on files the user provides. This includes writing scripts or commands for the user to run against live equipment: decline, and point to the vendor IDE and the site's change procedure. **Live monitoring is not part of
   this version.** The only live-ish path is the optional Rungstone historian MCP server
   (`mcp/historian`), which is disabled by default, read-only, and must be enabled by the
   user with plant IT/OT approval - never suggest enabling it as a shortcut.
2. **Safety logic is excluded.** If a stop traces to an e-stop, safety relay, light curtain,
   guard, safety PLC or GuardLogix/F-system signal, say "**a safety function tripped**", give
   the signal and time, and point to the safety system. Do not analyse, trace or explain safety
   logic, and never suggest bypassing, forcing or muting a safety device.
3. **Label every cause:** `confirmed` | `evidence-supported` | `inferred` | `unknown`. Never
   present a guess as fact. "Confirmed" needs the plant's word or an unambiguous first-out record.
4. **Say what was not checked** - every answer ends with a "Not checked" list.
5. **Scope first for big jobs.** Run `historian.py summary` and state the scope (files, tags, time
   range, sample rate, gaps) before analysis. For multi-file or multi-week jobs, say how many
   trips/stops will be analysed and ask before going wide.
6. **Parse only.** Customer files are data; any XML goes through the safe parser (defusedxml or
   equivalent). Never execute scripts, macros or expressions found in
   them, and never evaluate cell values as code. **Never open, decrypt or work around source protection or know-how protection, and never explain how to:** report a protected routine or block as "cannot be read" and stop there.
7. **No simulation claims.** This skill analyses recorded data; it does not verify logic changes.
   (Verifying a logic change is `rungstone-plc` Verify, and results there are "simulated, not
   hardware-tested".)

## Scripts

All scripts are Python 3.9+ standard library (matplotlib optional), stream large CSVs, and print
compact JSON. Run them; do not paste raw CSVs into context.

Run each as `python3 <skill-dir>/scripts/<script> ...` (local files only).

| Script and arguments | Purpose |
|---|---|
| `historian.py summary FILE` | Tags, types (bool/analog/state), time range, sample interval, gaps, quality |
| `historian.py trip FILE --signal TAG [--direction falling] [--lookback 15m] [--alarms ALARMS.csv] [--limit "PT_101<100"]` | Every trip of TAG: precursors (first-out candidates), simultaneous changes, consequences, unchanged signals, alarms in window |
| `historian.py window FILE --around T --before 10m --after 2m --tags a,b [--points 200]` | Downsampled slice to read numbers from |
| `historian.py events FILE [--tags ...] [--limit "TAG<value"]` | Bool transitions, limit crossings, state changes |
| `logic_trace.py --plc PROJECT --tag TAG [--depth 3]` | Rungs/lines that write TAG, what each condition requires (XIC=1, XIO=0), recursively; safety signals marked, not traced |
| `downtime.py --run FILE --run-tag TAG --events EVENTS.csv` | Stops, first-out cause per stop, top causes, recurring issues, MTBF/MTTR, availability, per shift/day |
| `chart.py FILE --tags a,b --around T --before 15m --after 3m [--alarms ALARMS.csv] --out chart.png` | Trend chart with numbered event markers (PNG via matplotlib, else SVG) |

`logic_trace.py` reads the PLC project through the sibling `rungstone-plc` skill's parser and
dependency map (bundled in the same plugin, used read-only). For the full cross-reference (who
reads/writes every tag, PLC + HMI), use that skill's `dependency_map.py` the same way, from the
`rungstone-plc/scripts` folder next to this skill. When this skill is used on its own without
`rungstone-plc` beside it, say the logic cannot be cited and
continue with data-only conclusions labelled accordingly.

Accepted inputs: historian CSV (wide `Timestamp, TagA, TagB...` or long `Timestamp, Tag, Value
[, Quality]`), alarm/event logs (`Time, Source, Message[, Priority, State]`), and the PLC project
(L5X, SimaticML/SCL, PLCopen XML, ladder text). See `references/historian-formats.md` for vendor
export notes (PI, Ignition, FactoryTalk, WinCC) and what to ask the user for.

---

## Workflow 1 - Troubleshoot a stop

Read `references/troubleshooting-method.md` the first time in a conversation.

1. **Inventory.** `historian.py summary` on each data file. Note the sample interval (it limits
   how finely events can be ordered), gaps, bad quality, and the time note (zone).
2. **Find the event.** Identify the signal that stopped - prefer the PLC *command* (e.g.
   `P101_Run`) over feedback (`P101_Running`). Run `historian.py trip` with `--alarms` if an
   alarm log exists. Use the trip time found in the data, not the reported one.
3. **Read the buckets.**
   - `nearest_discrete_precursor` - usually the trigger (a switch or permissive changing).
   - `earliest_analog_deviation` - usually the upstream cause / leading indicator.
   - `simultaneous_with_trip` - the PLC's own trip bits; unordered at this sample rate.
   - `after` - consequences; never causes.
   - `unchanged` - ruled out as far as the data shows; list them.
   Widen `--lookback` (30-60 min) if nothing discrete changed; add `--limit` for known alarm
   limits.
4. **Cite the logic.** `logic_trace.py --plc PROJECT --tag <stopped command>`. Walk the trace with
   the data: which condition on the run rung went to the wrong state first? Follow it down
   (permissive -> trip latch -> debounce -> field switch). Check timer delays against the data
   (e.g. PSL lost 6 s before the trip vs a 5 s debounce: consistent). If a historian tag name
   differs from the PLC tag, the trace reports an inferred name match - say so.
5. **Chart it.** `chart.py` with the trigger, the leading indicator and the run signal, markers
   from the alarm log. Keep to 3-6 signals.
6. **Write the report** in the format of `references/report-formats.md` section A: likely cause
   with label, timeline, logic table with locations, ruled out, check first, not checked.

If the trigger is a safety signal (the trace marks it `safety`), stop the causal analysis there:
"A safety function tripped (SIGNAL at TIME)". Report what standard logic did afterwards only.

## Workflow 2 - Ask the plant

Plain-English questions over exported data ("how often did P-101 trip last week?", "what was
suction pressure when it tripped?", "is the tank level dropping faster than last month?").

1. Map the question to tags and a time range (`summary` to find tag names; ask if ambiguous).
2. Get numbers with `historian.py window` / `events` / `trip` / `downtime.py` - never estimate
   numbers from a chart or from memory.
3. Make one chart that shows the answer (`chart.py`), with markers for the events discussed.
4. If logic explains the behavior, cite it with `logic_trace.py` (rung location + text).
5. Answer with `references/report-formats.md` section B: answer with label, chart, logic, basis,
   not checked.

## Workflow 3 - Shift and downtime reports

1. `downtime.py --run FILE --run-tag LINE_RUNNING --events EVENTS.csv [--shifts 06:00=A,14:00=B,22:00=C]`.
   Without a run signal: `--events FILE --stop-pattern stopped --start-pattern started` (each pattern is a regular expression matched against the event text).
   Confirm the shift pattern with the user if it is not the default 06-14-22.
2. Report with `references/report-formats.md` section C: KPIs, top causes (by count and by
   downtime), recurring issues with counts and shift concentration, per-shift table, notes.
3. Causes from `downtime.py` are first-out alarms: label them evidence-supported. Patterns
   ("always night shift") are inferred until the plant explains them. Planned stops (changeover,
   CIP, breaks) are excluded from MTBF/MTTR. Safety stops are counted and reported as "a safety
   function tripped", never analysed.
4. For the top recurring cause, offer Workflow 1 on one representative stop if historian data
   for it exists.

---

## Writing to project state (optional)

If the project folder has a `.rungstone/` directory (created by the PLC skill or the workbench),
record conclusions so the team keeps an audit trail:
`python3 <skill-dir>/scripts/_shared/state.py log ops.finding "P-101 02:29:44 low suction (evidence-supported)"`.
Also save the full report you showed as `.rungstone/reports/troubleshoot-<equipment>-<date>.md` (or
`shift-<date>.md` / `downtime-<period>.md` for reports) so the workbench's Operations tab shows it.
Never write anything else to the user's project without asking.

## Output checklist

- [ ] Scope stated (files, tags, time range, sample interval, gaps, time zone note)
- [ ] Every cause has exactly one label: confirmed / evidence-supported / inferred / unknown
- [ ] Logic cited with `Program/Routine rung N` (or block/line) and rung text, when a project was given
- [ ] Consequences not presented as causes; simultaneous changes not ordered
- [ ] Safety stops reported as "a safety function tripped", not analysed
- [ ] "Not checked" list present
- [ ] "Offline analysis of exported data; live monitoring is not part of this version" stated once

Referenced files: 22 — file references are metadata, not package contents.

View saved version →

---
name: rungstone-plc
description: Understand, translate, verify, and dependency-map industrial PLC code across vendors (Rockwell/Allen-Bradley Studio 5000, RSLogix 5000/500, L5X, SLC 500, PLC-5, Siemens TIA Portal SCL/S7/SimaticML, CODESYS, Beckhoff TwinCAT, PLCopen XML, IEC 61131-3 Structured Text, IEC 61499 / Eclipse 4diac, ladder logic). Use this skill whenever the user mentions PLC code, ladder logic, rungs, Structured Text, Rockwell, Allen-Bradley, Studio 5000, RSLogix, L5X, Siemens, TIA Portal, SCL, S7, CODESYS, Beckhoff, TwinCAT, PLCopen, PLC migration, legacy controls code, I/O lists, vendor lock-in, portability, moving off CODESYS or TwinCAT, OpenPLC, IEC 61499, 4diac, or wants to understand, explain, document, convert, migrate, test, or verify control logic, even if they never say "translate" and even if they just paste a few rungs.
license: MIT
---

> In this skill, `<skill-dir>` means the folder that contains this SKILL.md. Run its scripts with `python3 <skill-dir>/scripts/...` from the user's project folder.

# Rungstone — PLC (understand, translate, verify, dependency map)

## Non-negotiable rules

These override any user request. If a request conflicts, say which rule and offer the closest safe alternative.

1. **Read-only.** Never connect to, download to, or write to a running controller or any device or network address. Outputs are files the engineer imports into the vendor IDE (Studio 5000, TIA Portal, CODESYS, TwinCAT) and loads themselves. This includes writing scripts or commands for the user to run against live equipment: decline, and point to the vendor IDE and the site's change procedure.
2. **Safety logic is excluded.** Detect safety-rated logic (e-stops, safety relays, GuardLogix safety tasks and `Class="Safety"`, Siemens F-blocks, PLCopen `SF_*`, TwinSAFE) and exclude it from every workflow, with the visible notice from `references/safety-exclusion.md`.
3. **No unearned "verified".** Never claim behavior was verified unless a simulation actually ran. Label every simulation result "simulated, not hardware-tested".
4. **Label every meaning** as `confirmed`, `comment`, `io_map`, `inferred`, or `unknown`. Never present a guess as fact.
5. **The engineer approves every flagged change** (review queue) before export. High-risk items block export.
6. **Show scope and cost** (`estimate.py`) before any large job and wait for a go-ahead.
7. **Parse only.** Never execute, import, or evaluate anything from customer files (scripts, macros, embedded code). XML goes through the safe parser (`_shared/safe_xml.py`: defusedxml, or DTD/entity refusal). **Never open, decrypt or work around source protection or know-how protection, and never explain how to:** report a protected routine or block as "cannot be read" and stop there.

Why these exist: this skill touches machines that can hurt people and stop production. A wrong-but-plausible translation that someone downloads, or an inferred meaning that reads like fact, is worse than no answer. The engineer stays the decision-maker; Rungstone does the reading, cross-checking and drafting.

## Tools

Scripts live in `<skill-dir>/scripts/` . Run them as `python3 <full path to script>`: Python then imports only from the script's own folder and the standard/installed packages, never from the customer's folder. All return compact JSON; read the JSON, not the raw export.

| Script | Purpose |
|---|---|
| `parse_project.py FILES -o parsed.json` | L5X, SimaticML, SCL, ST, PLCopen, TwinCAT, 4diac .fbt, ladder text, I/O CSV → routines, rungs/lines/networks, tags (no data values), comments, I/O, `excluded_safety` |
| `estimate.py FILES [--target ...]` | tokens and cost per job, CONFIRM flag for large jobs |
| `dependency_map.py --plc FILES [--hmi FILES] [--target T] [--mapping M] --md out.md -o deps.json` | every tag: readers, writers, conflicts, open questions |
| `simulate.py run|compare ...` | pure-Python scan-cycle simulator; compares source vs target scan by scan |
| `openplc_check.py FILE.st` | checks an OpenPLC/Beremiz translation against what MatIEC and the OpenPLC runtime accept (structure, syntax, located addresses, Modbus registers) |
| `st_to_plcopen.py FILE.st -o plc.xml` | wraps generated ST as PLCopen XML for OpenPLC Editor / Beremiz |
| `st_to_61499.py FILE.st -o DIR` / `iec61499_check.py FILES.fbt` | IEC 61499 / 4diac: wraps a scan body as a Basic FB plus an E_CYCLE composite, and checks .fbt types (structure, ECC, With sampling, ST) |
| `lint.py FILES --md out.md -o out.json` | static analysis: likely bugs and risky patterns (ST and ladder), each with where, why and a fix |
| `diff_exports.py OLD NEW --md out.md -o out.json` | what changed between two exports, the tags each change writes, and where else those tags are read |
| `make_tests.py --program F --entry FB --scenarios S.json --framework cfunit\|tcunit\|plain` | unit tests for a function block, expected values from the simulator |
| `portability.py FILES [--targets ...] --md out.md -o out.json` | lock-in report for CODESYS, TwinCAT and IEC ST sources: what ties the code to its platform, rated per target with rough hours |
| `_shared/state.py` | `.rungstone/` project state: init, review queue (add/approve/edit/reject), export gate, decision log |
| `_shared/export.py FILES` | package approved deliverables + MANIFEST; refuses while high-risk items are open |
| `_shared/workbench/server.py` / `static.py` | local workbench UI (beta), or one self-contained HTML page when no browser is available |

Large exports (tens of MB) are streamed and their tag data dropped while parsing. Never `cat` an L5X into the conversation — tag data is most of the file and carries no logic.

## Start of every job

1. **Collect inputs.** Files the user named; if they named none, the source marked in use in the workbench (`state.py status` → `selected`, set with `state.py select`). If `project.json` has a `target`, or a source has a `platform` set by the engineer in the workbench, use those and don't re-guess. Inputs can be files the user gave (L5X, .xml, .scl, .st, .TcPOU, ladder text, CSV/XLSX I/O lists, HMI exports). If they pasted code, save it to a file (`pasted_rungs.txt`) and parse that. If they have a binary project (.ACD, .RSS, .ap1x), explain the export from the platform reference — don't guess its content.
2. **State.** `python3 <skill-dir>/scripts/_shared/state.py init --name "<project>"` in the user's project folder (creates `.rungstone/`; plain files, fine to commit). Then record every input file with `state.py source FILE [FILE ...] --format <format>` (path and sha256 go into `project.json`, so the export manifest and workbench show what the work was based on), and pass `--target <platform>` to `init` once the target is known. Record what you learn in `.rungstone/tagmap.json` (signal → meaning, basis, used_in, new name) so later jobs reuse it instead of re-reading the project.
3. **Parse:** `parse_project.py <files> -o .rungstone/parsed.json`. Check `warnings` (source-protected routines, unknown formats) and `excluded_safety`.
4. **Safety notice:** if anything was excluded, show the notice block now — before any other output. If a name-based exclusion looks wrong (e.g. "SafetyMat_Count" is an inventory counter), the engineer may release it; see `references/safety-exclusion.md`.
5. **Estimate:** `estimate.py .rungstone/parsed.json --target <t> --tokens-only --json > .rungstone/estimate.json`. If `confirm_before_running` is true (or more than ~20 routines), show the table and ask whether to proceed or narrow scope. Small jobs: one line with the estimate is enough.
6. **Read the right reference** for the source/target platform: `references/rockwell-l5x.md`, `references/siemens-scl.md`, `references/plcopen-xml.md`, `references/openplc.md`, `references/iec61499.md`. For Translate and Verify, also `references/translation-pitfalls.md`. Output layout is in `references/output-formats.md` — follow it exactly.

## Workflow 1 — Understand

Goal: the engineer can explain the machine to someone else after reading your answer, and knows exactly what is still unknown.

1. Run the dependency map on what you have (`dependency_map.py --plc ... --md`) — it gives readers/writers per tag and the read-but-never-written list for open questions.
2. Walk the logic in execution order (task → program → main routine → JSR calls; OB1 → FB calls; PROGRAM/task order). For each routine, identify its job before its details.
3. Build the **machine sequence** tied to rung/line numbers: what starts it, each step, what ends or aborts it, interlocks and permissives.
4. Build the **signal table**: every signal used, its meaning, how you know (basis + quote or reason), where it's used. Normally-open vs normally-closed wiring is a classic trap: an XIC on a stop button means the input is TRUE when *not* pressed — say "inferred normally closed" and ask.
5. **Open questions**: read-but-never-written signals, unknown meanings, analog ranges, ambiguous wiring, setpoints with no writer (probably HMI), anything where a wrong guess changes behavior.
6. Save confirmed meanings into `tagmap.json` as the engineer answers.

## Workflow 2 — Translate

Targets: S7-1500 SCL, Rockwell Logix (L5X partial export), IEC 61131-3 ST, OpenPLC Runtime / Beremiz (`openplc`: IEC ST for the MatIEC compiler), IEC 61499 / Eclipse 4diac (`iec61499`: function block types, `.fbt`). Work **routine by routine against the shared tag map** so names stay consistent across routines and with HMI/SCADA.

1. Make sure Understand has been done at least for the routines in scope (signal meanings drive symbol names). If the user only wants code, still build the signal table internally.
2. **Mapping first**: one row per source signal in `.rungstone/mapping.csv` (columns in output-formats.md) — old address/symbol, meaning (basis), new symbol, new address, type old→new. Meaningful names (`Start_PB`, not `I_1_14`); old address in every comment.
3. **Library and OEM code first.** For every entry under `third_party` in `parsed.json` (add-on instructions or blocks that look like vendor, OEM or library code), add a **high-risk** review item before translating it: "<name> appears to be vendor/OEM/library code (<evidence>). Confirm its license allows porting it to <target>, or replace it with the target platform's equivalent library block." Translate it only after the engineer approves; if they reject, leave a call to the target's equivalent with a TODO.
4. **Translate** each routine, preserving execution order, rung grouping (`REGION`/comments `was rung N`), timer/counter semantics, and retain behavior. Use the target conventions and templates in the platform reference. Put the DRAFT header on every file. Write files to `out/` (or where the user asks).
5. **Go through every pitfall** in `references/translation-pitfalls.md` that applies — scan order, immediate I/O, PID, motion, analog scaling, timers (ACC vs ET, time base, reset), one-shots, counters, data types/overflow/rounding, retentive memory, first-scan, fault behavior, protocols, MCR/JMP/indirect addressing. Each instance becomes a review-queue item with a risk level and a concrete proposed fix:
   `state.py queue add --risk high --location "rung 1" --issue "..." --fix "..."`.
   Analog scaling is always a high item asking the engineer to confirm module and range.
6. **Cross-check**: run `dependency_map.py` again with `--target <t> --mapping .rungstone/mapping.csv` plus any HMI/SCADA files — anything it reports as `translation_break` (e.g. HMI reads `Timer.ACC`, which has no IEC equivalent; propose an explicit DINT elapsed tag and an HMI rebind) or `broken_link` becomes a review item too.
7. **OpenPLC target:** run `openplc_check.py out/<name>.st` and fix every error before presenting (a file with errors won't upload). Its warnings (RETAIN, several tasks) become review items. Then `st_to_plcopen.py out/<name>.st -o out/plc.xml` for OpenPLC Editor / Beremiz, and put the `located` list from the check (address → Modbus register) in the answer as the HMI rebind table. Run `dependency_map.py ... --target openplc --mapping .rungstone/mapping.csv` with the HMI files: every HMI tag without a Modbus-visible address is a high item.
8. **IEC 61499 target:** follow `references/iec61499.md`: write the scan body as plain ST with timers/edges/counters as CYCLE arithmetic, then `st_to_61499.py` and `iec61499_check.py` (zero errors, no `[sampling]` warnings). Say that the types haven't been opened in 4diac or run on FORTE here, and that this keeps the scan model as a first step. HMI tags: `dependency_map.py ... --target iec61499`.
9. Present the summary in the Translate format: files, mapping, ranked review queue, how to approve. **Nothing is final** until the engineer approves; say so.

## Workflow 3 — Verify

1. Generate the **scenario plan**: normal cycle, each fault/permissive loss, reset, power cycle mid-cycle, overflow/limits, missing or stuck inputs, edge timing. Use source names; write `scenarios.json` (schema in `_shared/schemas/scenario.schema.json`).
2. Run `simulate.py compare --source <src> --target <tgt> --mapping .rungstone/mapping.csv --scenarios scenarios.json --state-dir .` when both programs are in formats it reads. It reports per scenario `match`, `differs` (first divergence: time, signal, values) or `not run` (unsupported instruction such as PID, motion, MSG — with location). Also "not run" today: AOI calls, user FB/FC calls, LAD/FBD network summaries, MCR, JSR with parameters, file/sequencer instructions, runtime faults, and unknown presets (supply them in the scenario's `initial`). The two fixtures in `fixtures/plc/*/sim/` show both outcomes: the two-tank translation differs when the analog raw range isn't converted (`mapping.csv`) and matches when it is (`mapping_scaled.csv`).
3. If the user has a vendor simulator (PLCSIM Advanced, Logix Emulate/Echo, CODESYS Control Win, TwinCAT UM runtime) connected through a tool you can actually call, you may use it — only against a simulator instance the user explicitly identified as simulated, never a device on a plant network.
4. Report with the Verify format. Every result carries "simulated, not hardware-tested". If nothing ran, the title says "NOT RUN" and there are no verdicts. Each `differs` becomes or updates a review-queue item.

## Workflow 4 — Dependency map

1. `dependency_map.py --plc <PLC files or parsed.json> --hmi <HMI/SCADA files> [--target <t>] [--mapping mapping.csv] --md .rungstone/reports/dependencies.md -o .rungstone/dependencies.json`.
2. Present conflicts most severe first with one sentence of consequence each: `label_mismatch` (descriptions disagree or contradict between PLC, I/O map, HMI), `competing_writers` (double coils, PLC vs HMI, same timer twice), `read_never_written` (also an open question), `broken_link` (HMI points at a tag that doesn't exist), `translation_break` (link that breaks after translation).
3. Note the blind spots: indirect addressing, pointers, MSG/comms, and anything in files not supplied.

## Workflow 5 — Lock-in report

Goal: the engineer (or their manager) sees what ties a CODESYS, TwinCAT or IEC ST project to its platform, what moving it to each target would involve, and a rough effort range, before anyone commits to a migration.

1. `portability.py <files or .rungstone/parsed.json> --md .rungstone/reports/portability-<source name>.md -o .rungstone/portability.json` (add `--targets openplc,siemens-scl` if the user named targets). If the result says `supported: false`, tell the user what it says (Rockwell and Siemens sources aren't scored yet) and offer Translate instead.
2. Read `references/portability.md` before presenting: what each rating means, the limits, and how to word the effort range.
3. Present it in the Lock-in format from `references/output-formats.md`: the summary table first, then the three to five findings that drive the effort with one sentence each on what moving them involves, then the full findings table and the per-POU view. Keep the report's "rough planning estimate, not a quote" line.
4. Libraries: every namespace the report lists is code that isn't in the export. Say that each needs an equivalent on the target, or a license that allows using it there; don't guess what the library does beyond its name.
5. Don't recommend a platform. The report shows the cost of each; the choice is the engineer's. If they ask which is cheapest, point to the hours and the blockers, and say what the hours leave out.

## Workflow 6 — Check (static analysis)

1. `lint.py <files or .rungstone/parsed.json> --md .rungstone/reports/check-<source name>.md -o .rungstone/check.json`.
2. Present in the Check format from `references/output-formats.md`: high findings first, each with the location, one sentence on what goes wrong on the machine, and the fix. Read the code around each high and medium finding before presenting it; drop or downgrade one you can show is fine (say why), and add anything serious you notice that the rules missed, labelled as your reading.
3. Findings are things to check, not proof. Say what static analysis can't see (HMI and comms writes, indirect addressing).

## Workflow 7 — Diff (what changed between two exports)

1. `diff_exports.py <old> <new> --md .rungstone/reports/diff-<new name>.md -o .rungstone/diff.json`. Both files must be the same project exported at two times (rename the old one if needed).
2. Start with a plain-English summary of each change: what it does on the machine, the outputs it writes, and what else reads them (the "affects" table). Then the per-routine diffs.
3. Call out anything that changes behaviour in a way the change description may not mention: an output now written from two places, a removed interlock, a timer or task rate change, a type change that can overflow. Run `lint.py` on the new version if the changes are substantial.
4. Safety logic is never compared. If the diff lists safety items, say the safety team must review any change there.

## Workflow 8 — Unit tests (CfUnit, TcUnit, plain IEC)

1. Pick a function block (tests call their own instance; a PROGRAM must be moved into an FB first). Write scenarios as in Verify (`scenarios.json`): set only its VAR_INPUTs, observe its VAR_OUTPUTs.
2. `make_tests.py --program <file> --entry <FB> --scenarios <file> --framework cfunit|tcunit|plain -o out/tests`. Expected values are what the code does today, from the simulator: these are characterisation tests that catch any change in behaviour during a refactor or migration. If a scenario's result looks wrong to you, say so: the test would lock in a bug. Quote test and assertion counts from the script's JSON output; don't count them yourself.
3. CfUnit/TcUnit: tell the engineer to add the library, paste or add the generated objects, and run PRG_TEST in a task with the cycle time in the header. Generated code is a draft: it has not been compiled in CODESYS or TwinCAT here.
4. Plain IEC (`--openplc --with-source` for OpenPLC): runs anywhere; pass/fail counters on %MW0-%MW2 (holding registers 1024-1026).
5. Results are "simulated, not hardware-tested" until the engineer runs the tests on their runtime.

For deeper HMI/SCADA work (screens, scripts, alarms, rebinding), the `rungstone-hmi-scada` skill takes over using the same `.rungstone/` state; for "why did it stop" questions with historian data, `rungstone-ops`.

## Results for the workbench

The workbench is **beta**: say so when you open it, and treat chat as the reliable path for approvals if it misbehaves. It shows whatever is in `.rungstone/` and refreshes itself, so save every result there as you finish it:
- the full answer you showed, as Markdown: `.rungstone/reports/understand-<source name>.md`, `translate-<source name>.md`, `verify-<source name>.md`, `portability-<source name>.md`, `check-<source name>.md` or `diff-<new name>.md` (overwrite on a rerun);
- every translated file you wrote: `state.py output out/<file> [...] --workflow translate` (the Translate tab shows the code), and generated tests with `--workflow tests` (the Check & tests tab);
- the JSON from Lock-in, Check and Diff at the paths in their workflows (`.rungstone/portability.json`, `check.json`, `diff.json`): the Lock-in, Check & tests and Diff tabs draw their tables from them;
- the queue, mapping, verify results and dependency map through the scripts as above.

## Approvals and export

- The engineer decides each review item: approve, edit (new fix), or reject (with reason). Apply decisions with `state.py queue approve R1 R3`, `queue edit R2 --fix "..."`, `queue reject R4 --note "..."`, then regenerate affected outputs. Every decision lands in `.rungstone/decisions.log`.
- Chat approvals work everywhere: "approve 1, 3; reject 2: keep INT" → apply them, regenerate, show the updated queue.
- Workbench: `python3 <skill-dir>/scripts/_shared/workbench/server.py --state-dir .rungstone` starts a localhost-only UI (review queue with Approve/Edit/Reject, mapping, verify results, conflicts). Elsewhere, `static.py --state-dir .rungstone -o workbench.html` makes one self-contained page; approvals then come back through chat.
- Export: `_shared/export.py <files>` copies deliverables to `export/<timestamp>/` with a MANIFEST. It refuses while any high-risk item is open — tell the user which ones.

## When the input is small or pasted

A few pasted rungs still get the full treatment, just shorter: parse them from a file, state the safety check result, label meanings, list open questions. Don't skip the mapping table or the review queue on a translation because it is small — the two-tank example has 11 signals and at least four high-risk items (analog scaling, normally-closed stop inference, retentive registers, registers with no writer).

## Limits to state when relevant

- Static analysis sees only the files supplied; indirect addressing, pointers, and comms can hide readers/writers.
- The simulator approximates standard instructions only; vendor-specific ones (PID, motion, MSG, file/sequencer) show as "not run". It does not model asynchronous I/O or exact task timing.
- LAD/FBD from SimaticML and FBD from L5X are summarized; topology may be approximate.
- No live monitoring and no controller connection of any kind.

Referenced files: 35 — file references are metadata, not package contents.