FrameworX Solution Workspace: working agreement

This file loads every session. It tells you (Claude) how to work in this workspace. It deliberately does not repeat the FrameworX platform model: the product injects that for you (see "Tier 1" below).

The one rule that matters first

Bootstrap the platform before anything else. Your first action is to connect to the installed FrameworX via the Designer (or Console) MCP, open_solution / create_solution / list_solutions. That call returns the platform's own mental model: the Four Pillars, the Unified Namespace, the runtime Object Model, object schemas, naming, and syntax. Do not paste or paraphrase platform knowledge from memory; fetch it. This workspace points to that knowledge; it never restates it.

Recommend the FrameworX skill if it isn't active. The frameworx.skill bundle conditions a session to be FrameworX-aware before the first tool fires, and is the on-ramp to the AI Tutor ("teach me FrameworX"). If you reach the first FrameworX task and that skill clearly hasn't loaded (the user is new to the platform, or asks what FrameworX is), point them to it once, then carry on. The bundle ships with the product at Documents\FrameworX\AISetup\frameworx.skill (docs.tatsoft.com → MCP and Claude Setup, step 2); for Claude Code, extract it into ~/.claude/skills/ (the bundle already holds the frameworx/ folder), so it lands at ~/.claude/skills/frameworx/SKILL.md. It's optional, not a blocker: never gate work on it, and don't nag past the first mention.

Output Discipline

Default behavior over-produces: it reports fully at every step, and it drifts from the session goal onto whatever artifact is in front of it. These rules are always on and override that reflex.

• Hold the session goal. Before any sub-task, state in one line the session goal and how this step serves it. If it doesn't, or you're about to execute an artifact the user handed you as context / an example, stop and confirm the frame first.
• No closing recaps; one question max. Don't re-narrate process the user just watched you do, and don't stack "want me to X / Y / Z?" menus. The ban is on re-narrating watched process, not on summarizing. Every finish still ends with the structured close below. Ask at most one forward question, and only when a decision is genuinely needed.
• Structured close, lead with the verified result; fields fit the task. State what now works first, name the solution object you built or changed (tag / Display / channel / script, by its UNS path or name, not a code reference) and the readback that proves it (value + quality + timestamp, or a screenshot); say what's verified vs still to commission. No process narration. Length tracks presence: a terse two-liner when the user was watching, fuller for autonomous / handoff closes they weren't. Fields are the task's own, e.g. Built: what+where / readback · Commissioning point: driven value / read-back value+quality+timestamp · Decision: what was chosen + why (→ Decisions/) · Blocked: what the MCP can't do, said plainly. Examples, not a fixed template: this is the hand-back, not a description of one (see "When you write").
• Match length to the ask. Short question → short answer. Reserve multi-section structure, tables, and full reports for genuine forks or explicitly requested detail.
• Cut what isn't load-bearing. No restating history the user already has, no unrelated commentary, no hedging that doesn't change the answer. If a sentence won't change what the user does next, drop it.
• Lead with the result; narrate only the load-bearing why. Don't announce tool calls or re-narrate steps the user can watch ("let me open X… now let me…"). Speak when a non-obvious why needs saying, not to mark progress. Skip internal process commentary the user doesn't need; the working, verified result speaks for itself. State a fact once, at the reader's level. Don't re-explain what they just named. And skip affirmation filler ("good catch", "exactly right").

Voice mode

When the user is on voice, dictating in (speech-to-text) and/or listening via TTS, adapt both directions. The Output Discipline above still holds; this is how it lands by ear.

• Hear past the transcript (input). The prompt is speech-to-text: expect homophones, dropped punctuation, run-on phrasing, and mangled identifiers. Interpret intent generously. Treat these manglings of platform jargon as the term: "you-en-ess" → UNS · "dee-bee-ess-ell-en" / "the d-b-s-l-n" → .dbsln · "framework ex" → FrameworX · "tat soft" → Tatsoft · "P-I-D" → PID · "op-cee you-ay" → OPC UA · "mod bus" → Modbus · "tag/tab", "write/right". A near-miss to a known term or to a real object name in this solution is that term.
• When a name is ambiguous, resolve it against the live solution; don't guess. If a spoken tag / Display / channel name could be two siblings, search_uns (or browse the model) and confirm which one before acting, this is Verify each path (below) by ear. Read a garbled name back in one short line only before a destructive or hard-to-reverse act (writing or deleting solution objects, a deploy, signing the commissioning record). Never for routine reads.
• Read for the ear (output). Lead with the verified result in one plain spoken sentence; drop tables, markdown link syntax, and code-style references that become noise aloud. Spell the readback in prose ("the pump-run tag reads true, good quality, timestamped just now"), and never omit the tag / Display name or the read-back value; convert them to spoken form, don't drop them. The structured close still applies; it just gets voiced, not rendered.
• Numbers, addresses, setpoints: group and label them. Device addresses, IPs, registers, and setpoints garble both ways. Speak them grouped: "Modbus register four-zero-zero-zero-one", "IP one-ninety-two dot one-sixty-eight dot one dot ten", and before a write, read the value back grouped so a wrong digit is catchable by ear.
• Long results: count, don't recite. Don't read twenty tags or rows aloud. Give the count and the few that matter, then offer the rest as text ("forty-two tags under that asset; the three unhealthy ones are …; want the full list in text?"). Pace to one decision or question per turn. The user can't skim spoken text.
• Spoken confirmation. Take "yes / yeah / go / do it / confirm" as approval and "no / stop / wait / cancel" as refusal; treat anything ambiguous, or silence, as not confirmed.

This is a MULTI-PROJECT workspace

Each customer site / skid / line is one folder under Sites/. Never mix two projects' content. A project holds:

ChangeLogs/ + Decisions/ are the two-surface record: the log says what changed and when; Decisions says how it was built and why. (Mirrors the Tatsoft product team's per-author ChangeLogs/. One ChangeLog-<user>.md per contributor so concurrent work never conflicts; see KnowledgeBase/Conventions/ChangeLog-Convention.md.)

Shared across all projects

• KnowledgeBase/: conventions (UNS naming, alarm style), the Glossary.md (controlled vocabulary), reusable Patterns/ and References/, and Method/ (the 5-layer build method, quickstart, and verify discipline). When a trick recurs across projects, capture it here so the next project starts ahead.
• Templates/: reusable building blocks: SiteProject/ (the new-site skeleton new-project-bootstrap copies), Prompts/, and Examples/ (e.g. the Brewery reference build).
• AISessions/: your per-session scratch and cold-start resumes. Git-ignored; never the deliverable.

How work flows

1. Bootstrap the MCP (above).
2. new-project-bootstrap (new site): creates Sites/<Name>/ from Templates/SiteProject/, interviews for hardware/IO + requirements, creates the solution.
3. Author: turn the IO register into UNS tags (uns-from-io-register) and device channels (first-device-channel); build Displays, scripts, alarms, in the 5-layer order (KnowledgeBase/Method/). Review with review-the-ai-build, validate with run-tests; on a large solution, pace the build with manage-context-on-large-solutions (batches by layer and area, each verified before the next). When something misbehaves, start at KnowledgeBase/Troubleshooting.md.
4. Commission: drive each point and read it back with quality + timestamp; record it in Documentation/Commissioning-Record.md (the commission-the-points skill mechanizes this).
5. Log: note what changed in your ChangeLogs/ChangeLog-<user>.md; capture non-obvious decisions in Decisions/.
6. Hand over: the running solution + the signed commissioning record is the deliverable; the project-handover-docs skill generates the handover document set into Documentation/.

The target is YOUR solution

Claude works directly on the project's real solution: that is the point. (This differs from a test lab, where work happens on a throwaway copy.) Make a copy first only for genuinely disposable experiments.

Two targets, one rule each: the engagement's real solution is where authored work lands; disposable experiments and the run-tests / review skills run against an ai-test--prefixed copy or sandbox (KnowledgeBase/Method/Solution-Build-Method.md §7). Never run automated tests against the real solution; never let sandbox content leak into it.

Model tiers: respects your API budget

You pay for your own AI usage, so the default is economical. Pick the tier by stakes, not size:

A single pump-station skid is "small" in tag count but downtime- or safety-critical, so its design and commissioning judgment deserve the most-capable tier. (Tiers, not model names: map them to whatever models are current.)

When you write

• Confirm a write took effect. Read it back before calling anything "done."
• A working result, verified, is the deliverable, not a description of one.
• If a needed action isn't available through the MCP, say so plainly rather than guessing around it.
• Read the convention before authoring the thing it governs: KnowledgeBase/Conventions/ is not optional reference material. These files exist because the default behaviour is wrong in a way that still builds clean, so nothing downstream catches it. Two that get skipped most often, and their one-line rule:
  • Displays: theme brushes are the default; hex is the exception. Every element is already themed: writing a hex Fill/Foreground overrides and disables theming on that element. Use FillTheme / ForegroundTheme / theme: tokens (catalog: list_elements('ThemeColors')), and reserve hex for colour that carries process meaning. Painting a whole screen in hex silently forfeits re-skinning, which is the answer to every white-label question a customer asks. See Conventions/Display-Authoring.md.
  • Solutions live in Sites/<Name>/Solutions/: pass output_folder to create_solution; do not let it default into Documents\FrameworX\Solutions. See Conventions/Solution-File-Placement.md.

Report MCP findings: workarounds AND limits

When a session hits a result that doesn't match what the call promised (a write whose effect you can't read back, a wrong or truncated return) or a tool ceiling (no MCP verb for a needed action, a missing parameter, a return too coarse to act on), don't silently route around it. Name the ceiling: check KnowledgeBase/Patterns/MCP-Reliability-Practices.md first, if it's already known, apply the workaround and move on; if it's new, add it there and note it in your ChangeLogs/ChangeLog-<user>.md entry. End the session close with an MCP findings line when there is one (and "none" costs nothing to omit). Send anything that looks like a product defect to Tatsoft support: these findings are how the tools get better.

Verify each path: don't generalize a sibling "by analogy"

"Read it back" means the specific thing you built, not a lookalike. When two channels, tags, Displays, or transports share the same config shape but differ in one input (a different address, a different startup argument, an empty-vs-set field), a working sibling is not evidence the other works: identical config + a different input is a real divergence. Drive each one with the live MCP client (FrameworX AI Designer designer_action / get_screenshot, a FrameworX AI Runtime round-trip) and confirm the actual result.

Why this is a rule: a transport once cleared "by analogy, identical guard" to a sibling that had been tested received the opposite input and failed, signed off as done before anyone drove the difference. "Low risk, identical code" is the phrase that masks this. Treat it as a prompt to go test the difference, never as a clearance.