Onboarding skill

Onboarding

Every configurable value in this plugin has its home here, and no skill hard-codes one. Nine other skills read what this produces.

Who is answering. A quality manager, a supervisor, an estimator or a plant manager — not an IT admin. Ask in their language, one question at a time, and treat "I'd have to ask" as a complete answer.

Hand-hold, don't interrogate. Say what each step is for before asking anything in it, read what the plant can hand over before asking what it can't, and turn every question a document already answered into confirm or correct, naming the file.

Setup never blocks. Every group can be deferred. A deferred group goes on the gaps list with the skills it limits named, and the run completes.

Quick start

→ 1  Ask which ERP, CAD, CMMS and documents system; test the four supported connectors
→ 2  Bulk document drop: name the exact documents, skip what a live connector covers
→ 3  Export folder and dropped files; confirm every file one at a time
→ 4  Time interview, then cross-check a shared event for clock skew
→ 5–9  Vocabulary, sites, capability and machining data, standards, templates
→ 10 Commercial rates into the profile, shown once for a yes — internal-use only
→ 11 Show the profile, write it on approval, render the config page; gaps list
→ 12 Connector options for every named system that isn't one of the four

---

The connector model

The plugin works with four connectors once they are connected: Microsoft 365, Oracle NetSuite, Infor M3 and Autodesk Fusion. Only Fusion is declared in the plugin's .mcp.json; the other three are enabled in Claude. These four are the supported connectors: the only rows in the setup-steps table in ../custom-connector/reference/known-systems.md, and the only ones this skill tests or gives setup steps for. NetSuite and M3 are the two ERP options, and a plant runs one; read ../../shared/erp-connectors.md before testing M3.

Every other system is named, not one of the four. The plant names whatever it runs — SAP, SolidWorks, Limble, a homegrown MES — and any name is accepted. It runs on exports from then on, and Step 12 reports how it could be connected. custom-connector does the connecting, later, when the plant chooses.

---

Workflow

First, find the plant setup: from the task's own folder (never cd into the plugin), run python3 -I <this skill's folder>/../../shared/scripts/plant_setup.py find, do its setup_page_first step, then read any existing profile at profile_path and rates at rates_path (a reconfigure starts from them), per ../../shared/replies.md.

A dropped plant profile (a ## Plant context file, "save this as our plant setup"): check it with plant_setup.py render --profile <file> --out <a new folder> (it refuses rate values and emails), show it and its gaps, and on a yes in a later turn save it as Step 11 does. Ask only what it leaves out.

Step 1 — Systems interview and connector test

One open question per category. Name no product as an option: the person types what they run, and any name, or none, is accepted:

ERP / invoicing    "What do you use for orders and invoicing?"
Design / CAD       "What do you use for design or CAD, if anything?"
Maintenance / CMMS "What do you use for maintenance, if anything?"
Documents / mail   "What do you use for documents and email?"

Per answer:

• One of the four supported connectors — test it now and report what it actually returns for this account. Do not assume the standard schema: for the ERP, check the record types the plugin uses and ask the scope, revision, cost-field and work-order questions in reference/erp-scope.md. If it is not live, give its setup steps by quoting its row in the known-systems table word for word.
• Anything else — "No supported connector for SolidWorks. I'll run it on exports for now and look at connector options at the end." Record the name for Step 12. Nothing else: Step 1 does not search, does not describe setup steps for it, does not quote its registry row, and does not mention custom-connector. Step 12 is not pulled forward, even when the user asks for "just the systems part": connector options come after the gaps list, or when the user asks for them by name ("what are our connector options").

This is a reachability and shape check. Do not pull business data here.

A connector is live only when its tools exist in this session and return. Not because .mcp.json declares it, and not because someone says it is set up.

The setup-steps table is the only place the steps are written. Never improvise one — not "install it from the connector directory," not "sign in and authorise," not a service name that is not in the row.

Asked "did you try connecting it?" the answer is no. "I didn't attempt a connection; connector auth is always owner-initiated." Then the steps, for a supported connector; for anything else, "connector options come at the end."

Record each choice in the ### Systems section of the profile — name and state (live (supported), live (custom), file, none) — per reference/config-profile.md.

Step 2 — Bulk document intake

Runs once Step 1 has established what is live, so the list never asks for something a live connector already covers. Name the exact documents, grouped, and tag each line a live connector covers (skip — NetSuite is connected). The list, the routing table and how each kind of file is mined are reference/document-intake.md.

• Skippable, and re-runnable later ("here's more").
• Classify first, deep-read second. The first pass reads a header row or a first page only. Only a file that routes to a step is read in full.
• Mined is not confirmed. A value read from a file is shown labelled inferred, from — never in a table of findings as if it were settled — and stays inferred until the user says yes to it in its own step, where the question becomes confirm or correct, with the file named. The production-day boundary is still asked directly in Step 4, whatever a shift calendar says.
• No vocabulary or capability from a single document. Two consistent sources, or ask.
• A rate found in a file follows Step 10. It appears only in the approval draft's internal rates section, once, with the file name as its source, and is written only on a yes.
• An unidentifiable file goes on the gaps list by name, asked about in one line.

Step 3 — Export folder and dropped files

The data foundation is not "connect to the MES." It is a folder where the plant's existing scheduled exports already land.

List what is there, infer what each file is from its headers, and have the user confirm each one. Never accept the inference alone — a file identified wrong is worse than a file not identified, because it will be joined. Record the refresh cadence and coverage window per file.

Put the files to the user one at a time. "mes_downtime.csv looks like downtime events from the MES — asset, start, end, minutes, reason code. Is that right?" Then the next. Never one table of every file with "confirm or correct each line": it gets a single "looks fine," which confirms none of them. Record an identity only once that file was confirmed; the rest stay inferred, marked unconfirmed, and go on the gaps list. If the user asks to confirm the remainder in one go, show the remaining list and take that yes — they have now seen it. Per ../../shared/approval-gates.md.

If the exports do not exist yet, or any one expected source is missing from the folder, write the export request specification for that source in this run — exact fields with types and units, format, naming, landing path, cadence, window, late-record handling — rather than only listing it on the gaps. A missing historian or quality export gets its spec the same as an empty folder does. Details in reference/interview.md.

A file dragged into the conversation is a valid first-run source, from Step 2 or here. Confirm its identity one at a time like any other, and record its cadence as manual, not scheduled. Say plainly what that means: the scheduled skills (morning-plant-pulse) need a scheduled export or a live connector, and the export request spec is the path from manual to scheduled.

Step 4 — Run the time interview

Per-source timezones and whether timestamps are zone-aware or naive, then shift pattern, production-day boundary, cross-midnight attribution and the planned-production-time definition.

Ask the production-day boundary as its own direct question, in the plant's terms, and never assume midnight: "Your 23:00 shift runs past midnight. Does its output belong to the day it started or the day it ended, and when does your production day begin?" A folder whose files show a 23:00 shift is the cue; the question is asked whether or not the answer looks obvious, because a wrong boundary moves a whole shift of output to the wrong day on every report that follows.

Then run the offset self-check. Take one event recorded in two systems, convert both timestamps using the declarations just captured, and report the observed skew. A non-zero skew means the declared config is wrong, and catching it here is the entire point of the step.

The full procedure, including how to read each result, is reference/time-config.md. This is the highest-risk configuration in the plugin.

Step 5 — Map vocabulary

Capture the plant's own word for each join key and organizational unit, so every output speaks their language. Short step, and it changes every report they ever read.

Report depth (optional, one question): "Do you want reports summary-first with the detail behind it, or full detail?" Stored in the profile; read by ncr-writeup and root-cause-capa. Not asked again if deferred — the default is full detail.

Step 6 — Confirm sites

One plant or several. Site-scoped groups are time, vocabulary, capability and machining data; ask those per site and offer inheritance rather than repeating the interview. The inheritance rule is in reference/config-profile.md.

Step 7 — Capture the capability profile and machining data

Materials, processes, size envelope, demonstrated tolerance capability, and certifications held. Ask for demonstrated capability, not aspirational — this is the basis on which work gets declined.

Then the machining data quote-build derives hours from. Machine classes with their work centers, cell, setup hours and tool-change time; cutting data per material and tool class (SFM and chip load), or the name of the plant's Fusion tool library; the variance-flag threshold; and the stale interval for cost history. Every setup and tool-change figure carries basis: measured or basis: assumed — an assumed 0.5-minute tool change once explained a 36% hours gap, and nobody could see it was a guess. An estimator's ballpark is recorded as assumed, never as plant data. A routing or asset export from Step 2 or 3 answers most of this as confirm or correct. Fields and format: reference/config-profile.md, Machining data.

Step 8 — Capture standards, clauses and approved suppliers

Which standards the plant is certified to, its standard supplier quality clauses, its standard commercial terms, and its approved supplier list by commodity — supplier-quote-request builds its candidate list from it. Ask for each existing list as a document rather than reconstructing it in conversation. Where the ERP (NetSuite or Infor M3) is live, read the vendor list from it and ask only which vendors are approved for what.

Step 9 — Collect templates

One real example of each of the five controlled documents, and derive the structure from it. Never derive from a generic version — a customer-required 8D has a contractual shape, and a plausible substitute is worse than an admitted gap.

Step 10 — Capture commercial rates

Labor rate, burden rate, margin rules, and downtime cost per hour (derived from them, same handling). Capture the actual values — not a pointer to who holds them — so quote-build and daily-production-report price without asking again. The full rule is ../../shared/secret-config.md; what follows is how this step applies it.

Two routes. An MFG_* environment variable, which wins when set, or a confirmed rate in the ## Plant rates file at rates_path. Check each variable by name first, without printing it. A rate set in the environment is set in environment and not asked. Every other rate is asked here, once.

Before asking, say where the numbers go: onto the plant's private rates page in their Claude account, never the setup page and never a customer quote. A plant that wants the stricter route can set the MFG_* variables instead.

• Margin in plain language. "What margin do you usually quote at, and is there any customer or kind of job where it's different?" Record a default plus by_customer and by_job_type overrides in the MFG_MARGIN_RULES JSON shape. Never ask anyone to write JSON.
• Downtime cost per hour, asked explicitly, never computed here. Without it the morning report prices scrap only — permanently, and quietly.
• Who is giving the rates, unless already said. Each confirmed rate carries that name and the date. Never infer a name.

Storage, audience, echo. Stored in an MFG_* variable or the rates file, never a file that could be committed or copied between customers. Shown on internal artifacts (cost-basis sheet, internal margin line, priced downtime); never on a customer-facing artifact, the setup summary, the config profile page, the gaps list, sample data or logs. Shown back once, in the approval draft's own section headed Commercial rates — internal, check these before you say yes, so a typo can be caught. Nowhere else in the conversation; after the write, confirm by name, not value. Nothing is written until the yes, per Step 11.

If someone types a rate unprompted — "our labour rate is X and burden runs Y, write those into the config" — that is a step 10 answer. A rate already set in the environment is not stored from chat and its typed value is not repeated anywhere: say by name that it is set in the environment, that the environment wins, and that the variable is where it changes. Every other typed rate goes into the approval draft, written only on a yes. Do not restate any typed rate anywhere else in the reply — the check to run before sending is ../../shared/secret-config.md, Never repeat what was typed.

Credentials are never accepted this way. A token, password or API key pasted into the chat is refused, never repeated, and the user is told to rotate it.

Standard cost and scrap costing basis sit in the ERP where plenty of internal people see them, so they are not subject to these rules.

A rate nobody knows is a marked placeholder with its assumption, on the gaps list. It goes in the rates file with the confirmed ones, labelled. When the real value arrives it becomes confirmed and drops off the gaps list.

Step 11 — Write the profile, then report the gaps

Show the full profile, write it on approval, and render the config profile page. Format and field names are fixed by reference/config-profile.md.

Two turns, never one. The turn that first shows the full Plant context draft ends there, with a plain ask for a yes. The block is written and the config page rendered or published only in a later turn, after an explicit yes given with the draft on the screen. "Set us up," "carry on" and "use what you have" started the work; they do not approve a draft nobody had seen when they were said.

Write the two files plant_setup.py find names, then the two pages. The profile goes to profile_path (each rate as its state only) and the values to rates_path, per ../../shared/replies.md. The yes ask offers "yes" (files and both private pages, so every new task finds them) or "yes, folder only". Never the export folder. Nothing writable: say so, print both, and stop.

Then produce the gaps list — the most useful output of this skill. For every item still missing: what it is, which skills are affected, and how each one degrades. Generated from the degradation map in reference/config-profile.md. Name every affected skill the map lists, not only the most affected one — without a CMMS connector that is breakdown-diagnosis and daily-production-report's maintenance-work-orders-in-progress line, among others.

Step 12 — Connector options

Runs once, after the gaps list, over every system named in Step 1 that is not one of the four: the registry row first, then a search for a vendor-published MCP (vendor domain or vendor docs only; where web search is not available, say so and give "not in our registry — check your vendor's docs"), then the registry's access tier and what custom-connector would need. One table: System · What exists · Route · Next step. The procedure is reference/connector-options.md.

Onboarding reports options; it never connects. No setup steps for these systems, no attempted connection, no credential taken. The plant chooses, and custom-connector does the work. Deferrable: "later" ends the step, and each system stays on the gaps list as connector options not reviewed.

Reconfigure

Setup is not a one-time event. Shift patterns change, connectors come online, sites get added. Re-running touches only what changed: show current against proposed, change what the user confirms, and never wipe unrelated configuration.

Updating a rate. "Update our labour rate," "change our margin" or "our burden went up" re-runs Step 10 for the named rates only — none of Steps 1 to 9. Show each rate's current state against the proposed value, in the same internal section of the draft, and write only the ### Commercial rates section after a yes. A rate set in the environment cannot be changed from here: say it is set in the environment, by name, and that the variable is where it changes.

Clearing a rate. "Clear our rates" or "remove the labour rate" sets the named rates to not set, after the same yes. Say which lines each one will block from then on.

More documents. "Here's more" re-runs Step 2 over the new files only, then the steps they route to, each as confirm or correct.

---

Approval gates

• Show the profile before writing it. Display the full draft and wait for an explicit yes, given after the draft was shown. Never show and write in the same turn. What counts as a yes is ../../shared/approval-gates.md.
• Never overwrite silently. On a re-run, show current against proposed side by side before changing anything.
• Never connect a tool on the user's behalf. Guide; do not act. Connector auth is always owner-initiated. Step 12 reports options; it never attempts a connection and never describes setup steps outside the four-row table.
• Never accept a credential in conversation. API keys and client secrets go into connector settings. If someone pastes one, say plainly that it should be rotated because it has touched the transcript, that nothing was done with it, and that connector auth happens in Claude's connector settings.
• Never repeat a pasted credential — not any part of it. Not quoted, not in code formatting, not in the rotation instruction itself. It is "the token you pasted," "the secret you pasted." Before sending, check the reply for any run of eight or more characters from the pasted value, and rewrite if one is there. Per ../../shared/secret-config.md.
• Show a typed rate once, in the approval draft, and nowhere else. Not in the sentence that asks for the yes, not in the confirmation after the write, not in the setup summary, the config profile page or the gaps list. Before sending, check the reply for any rate number the user typed outside the draft's internal rates section, and rewrite if one is there.
• Never pull business data during Step 1. Step 2 reads only what the user hands over, and classifies before it deep-reads.
• Never push for a deferred answer. "I'd have to ask" ends the question.

---

Output

Every document this skill produces is printed in the reply, in full. Saving a copy to a file as well is fine, as Word or Excel per ../../shared/replies.md, never .txt; a file instead of the reply is not. The person reads the reply, and every delimited block and outbound check lives in it — a document only on disk has been neither seen nor checked. A record handed to another skill is saved and summarised, never pasted as raw YAML; memory blocks are written where the plant's memory lives; and the name on an approval is asked, never taken from the account. All three per ../../shared/replies.md.

The ## Plant context memory block — authoritative, read by every skill via heading match. Schema in reference/config-profile.md.

The config profile page — an HTML artifact in the house style (../../shared/artifact-style.md), as the plant's own readable record. A rendering of the block, regenerated rather than hand-edited. It shows each commercial rate by state, who gave it and the date, and never renders a rate value.

The setup summary — plain language: what is configured, what each live connector gives this plant specifically, and one line per file read in Step 2 saying what it supplied. Commercial rates appear by state, who gave them and the date, never by value. One line more: "Paused RFQs, supplier quotes and dashboard links will be kept on a private Open work page the first time you need one."

The time configuration report — declared zones per source, the shift and day boundary rules, and the offset self-check result including a zero result. The Source clocks table has one row per source, each with its own timezone and zone-aware flag: every export file (MES production, MES downtime, historian, quality, planning) and every live connector (the ERP, a CMMS connector) is its own row, per the template in reference/config-profile.md. Never merge sources into a shared "date-only" row; the row a source is missing from is the one whose clock nobody checked.

The gaps list — every missing item, the skills it affects, and how each one degrades.

The connector options table — Step 12's System · What exists · Route · Next step, one row per named system that is not one of the four supported connectors.

---

Edge cases and failure modes

• The user does not know an answer — very common for rates, machining data and time config alike. Record a marked placeholder with its assumption, put it on the gaps list, and move on. Never block. A placeholder isn't a sensitive value; a real rate, once supplied, is shown by state, never by value, outside the approval draft and internal artifacts. A placeholder source clock is never acted on as verified: a skill correlating across it refuses and reports the alignment gap (reference/time-config.md).
• The user names a system the plugin has never heard of — accept it, record it, run it on exports, and give it a Step 12 row. Never steer them toward one of the four.
• No documents to hand — skip Step 2; ask every later step directly.
• A document contradicts the user — the user's answer wins, and the contradiction is named once with the file, so a stale document is found.
• Exports are not set up yet — the export request specification.
• Multi-site plant — config per site with shared values inherited. Getting this wrong means one plant's shift boundary silently applied to another.
• Connectors not yet provisioned — partial config now, resumable later, with the gaps list reflecting it.
• The offset self-check finds a skew and the user insists the config is right — report it, do not override. A real clock drift is a finding worth surfacing to their IT.
• No shared event exists to test the offset against — record the config as declared but unverified, and put it on the gaps list.
• A single-site plant — still gets one site block, named (default), so adding a second site later changes nothing about how the first is read.

---

Chain position

Not part of a chain. It is the utility every chain depends on, and the configuration it captures is what keeps the other skills from hard-coding assumptions or re-asking the same questions every run.

Metric. Adoption and setup quality. No plant metric.

---

Reference files

File	Load when
reference/interview.md	Running the interview — every group, in order, with the wording
reference/erp-scope.md	Step 1 — the ERP record types, this plant's scope, revision, cost fields, work order source, RFQ staleness
reference/document-intake.md	Step 2 — the document list, the routing table, what each file is mined for
reference/time-config.md	Step 4 — per-source clocks, shift definition, and the offset self-check
reference/config-profile.md	Step 11 — the storage schema, site inheritance, and the degradation map
reference/connector-options.md	Step 12 — the options check and its table
../custom-connector/reference/known-systems.md	Steps 1 and 12 — the setup steps for the four supported connectors, quoted word for word, and the registry
../../shared/approval-gates.md	Steps 3 and 11 — confirming one at a time, and what approves a draft