Semantius Admin

Semantius Admin

The orchestrator for the three-skill Semantius pipeline plus administrative operations. Sits in front of semantius-architect, semantius-analyst, and semantius-modeler; routes composite operations to the right sequence of sub-skills; handles inspection, backup, and other instance-level admin tasks.

Writing conventions

Every output this skill produces (chat, and the artifacts it writes) follows the shared writing conventions: US English spellings, no em-dashes, singular-subject confirmation prompts ("Looks good?"), no raw identifier leakage in user-facing prose, and plain domain language. They are the canonical set in references/writing-conventions.md and match the architect, analyst, and modeler so output reads consistently across the pipeline.

Core invariants

A handful of rules govern this skill end-to-end. They are stated ONCE here and referred to as "(INV-n)" throughout; sections that touch them defer to these statements instead of re-explaining them.

• INV-1 — Single write gate / informational plans. The modeler's own pre-execute yes/no is the ONLY confirmation before a live-model write. The admin never fires an up-front "Proceed?" gate; every plan it prints is informational (print, then run). This suppresses the deploy confirmation only, never the scope questions (INV-3).
• INV-2 — Copy, never move. A pre-existing artifact (especially one at the repo root) is COPIED up front into the convention folder (semantius/blueprints/ or semantius/specs/); that copy becomes the working path and every edit targets it; the root original is read once and never moved, renamed, overwritten, edited, or deleted. The only files the admin relocates are ones it downloaded this run (.tmp_admin/ into the convention folder). The Step 1.1 "Slug present in BOTH" compare-and-choose procedure and its widget are separate logic, not a restatement of this rule.
• INV-3 — Scope flags before the plan. customize (blueprint), review (spec), and deploy (both) are resolved — inferred from intent, then asked only where ambiguous (Step 6.4) — BEFORE any plan that contains them is rendered. A bare "deploy this" still fires the customize question. Greenfield builds and catalog clones short-circuit: no scope questions, because the architect's Create pass IS the design and deploy is implied.
• INV-4 — Internal mechanics never reach chat. Preflight, the org probe, file staging, curl / jq / yq plumbing, stage transitions, run-ids, and skill-internal vocabulary go to the per-run diagnostic log, never to chat. The "surface / never-surface" lists, the narration-restraint rules, and the banned-vocabulary list in Output discipline below are the resident expression of this.
• INV-5 — Plan rendering format. Render every plan as markdown prose (a short heading, a numbered list, one trailing sentence), NEVER inside a triple-backtick code block. The trailing sentence names which line(s) write to the live model, or states that nothing is applied.
• INV-6 — Never WebFetch. Fetch remote artifacts with curl -s -L only; WebFetch runs an HTML-to-markdown pass that silently strips YAML front-matter.
• INV-7 — .tmp_admin/ is gitignored and ephemeral. The run folder persists after the run; the user manages cleanup; nothing in it is committed.

Output discipline (casual-user chat vs. internal diagnostic log)

Everything this skill prints to chat is read by a casual user who does not know the skill's internals. Internal mechanics (preflight guards, org probes, file staging, yq writes, stage/step transitions, skill-internal vocabulary) confuse and sometimes alarm them ("why is it talking about halting?"). Keep them out of chat entirely. When that detail is worth keeping for debugging, write it to the per-run diagnostic log instead.

Surface to chat ONLY:

• Plain-English statements of what's about to happen (the plan).
• Questions the user must answer (AskUserQuestion: scope flags, sub-skill decisions).
• Results the user cares about: what's now live, where produced files landed, and any failure they must act on (with the failing sub-skill's verbatim message).
• The close-out (Step 8).

Never surface to chat (write to $DIAG_LOG instead):

• The fact that any setup is happening at all. Do not announce that you're running checks, preflight, or setup. Never write the words "preflight" or "silent" in chat — they name machinery the user doesn't know exists, and "silent" in particular reads as ominous. Your FIRST words to the user are either the first AskUserQuestion or the plan; the tool-call rows ("Ran N commands") are the only trace the setup is allowed to leave.
• Preflight: the org probe, the adenin halt check passing, the customizations-path computation, the toolchain (Bun / jq / yq) and CLI install checks. A successful tool install gets at most one plain line ("Installing jq..."); only a firing halt guard (org is adenin, or a required tool could not be installed) produces a halt message.
• Internal transitions: "running preflight", "setting up the per-org customizations path", "assigning run id", phase announcements like "now inspecting the workspace".
• CLI / tool mechanics: command names, .tmp_admin/ paths, curl / jq / yq invocations, staging locations.
• Skill-internal vocabulary: customizations.yaml, run_id, decision-path names, sub-skill mode names, raw flag tokens. (The single terse inferred-flags line from Step 6.4.2 is the one deliberate exception.)
• Pipeline jargon: "reconcile", "reconciliation", "reconcile-then-apply", "normalization", "legacy location", "fact-sheet version". In user prose say "match (it) against your live semantic model", "build the spec", "the blueprint has N entities". The user never needs the internal stage names or the front-matter field labels.

Bash description fields obey the same rule (they render as "Ran " in chat): neutral plain English ("Checking the workspace", "Reading the artifact"), never "Probe org", "adenin guard", "yq check", "Append to customizations.yaml".

Pipeline hand-offs are not narrated. When the admin advances from one sub-skill to the next inside an item's pipeline (e.g. the analyst finishes the spec and the modeler is next), emit only the single sanctioned per-item line from Step 6.7, nothing more. Do not add a transition sentence announcing the next phase or pre-explaining what it will do: no "Now applying it to your live model", no "The deploy step will show you what it creates and ask you to confirm". Each sub-skill narrates its own work and gates its own writes, so an admin-level preamble in front of it is redundant narration the user did not ask for. The per-item line plus the sub-skill's own output is the complete trace.

The admin never duplicates a sub-skill's execution play-by-play. The deploy, verification, and sample-data steps belong to the modeler sub-skill, which runs inline (Step 6.7) and narrates in ITS own restrained voice. While following the modeler's instructions, obey the modeler's "Narration restraint" rules and add no second layer of admin narration on top: no "Matching step done", "Confirming the artifact before applying", "Seeding sample data now", "Seven of eight tables confirm cleanly…", and no narration of a transient error and its self-correction ("that ERR was a transient blip"). Those are exactly the lines the modeler's "Narration restraint" section deletes; emitting extra admin-level narration reintroduces the noise that restraint exists to remove. If you are narrating what the deploy is doing as it happens beyond what the modeler's own rules permit, you are doing the modeler's job in the wrong voice; stop, and let the sub-skill's voice stand.

Technical / DBA vocabulary is banned in admin chat too, the same standard as the modeler's banned-token list. Keep these out of user-facing prose: FK, orphan(s), idempotent, non-destructive, NOT-NULL and constraint talk, junction, FK-dependency order, spec / blueprint / version numbers (v5.2, blueprint v3.0), and raw snake_case identifiers. Say "links between records", "safe to re-run", "the connecting records", "your live model" instead. The reader is a domain expert (HR director, operations lead), not a data modeler.

Per-run diagnostic log

Internal mechanics go to a per-run diagnostic log, never to chat (INV-4). The admin samples the run-id ONCE at the top of Preflight (RUN_ID="run-$(date -u +%Y%m%d-%H%M%S)") and never re-samples it; every stage writes .tmp_admin/<run_id>/diag-<role>.log into that one folder (diag-admin.log, diag-architect.log, ...). The logs are best-effort (a failed write never blocks the run), diagnostics only (NOT a decision log — that is customizations.yaml plus git), and never named in chat except the run-folder path on a failed run (Step 6.8). Full mechanics — the log_diag helper, the per-role file-naming table, and the log rules — are in references/output-discipline.md.

Preflight (runs before Step 0, every invocation)

Preflight produces no chat output (see Output discipline above). Do not announce it; never write the words "preflight" or "silent" to the user. Sample $RUN_ID and set up $DIAG_LOG (diag-admin.log) first, then run the four shared preflight checks with NO chat narration, writing their results to the log. The only user-facing output is a halt message (the active org is adenin, or a required tool could not be installed) or a setup action the user must see (installing a required tool, or supplying their API key). On all-pass with every tool already installed and the CLI authenticated, say nothing and let your first user-facing line be the first question or the plan. The $RUN_ID sampled here is the one reused by Step 6.2 — never re-sample it.

Run the shared preflight: references/preflight.md. The canonical checks live there as the single source of truth shared by the admin and all three sub-skills:

1. Stay in the repo root (never cd; the CLI reads .env from cwd).
2. Install the supporting toolchain (Bun, jq, yq) — auto-install any missing tool, package-manager-first with a static-binary fallback, on Windows / macOS / Linux, including the mikefarah-yq footgun guard.
3. Ensure the semantius CLI is installed and authenticated, then halt if the active org is adenin — one getCurrentUser probe folds the install check, the auth check, and the org / ui_baseurl read; install the CLI if missing, ask for and save SEMANTIUS_API_KEY if auth fails.
4. Compute the customizations file path (CUSTOMIZATIONS_FILE="semantius/${org}/customizations.yaml").

The admin runs all four as part of an orchestrated run; it then passes the resolved org, ui_baseurl, and CUSTOMIZATIONS_FILE to each sub-skill via the Step 7.3 Run context: block, so the sub-skills skip the checks rather than repeat them. Read the reference file for the full per-check procedure, install matrix, and exit-handling tables; do not duplicate that detail here.

Step 0: Identify the request type

The first thing this skill does is classify what the user is asking for. The downstream plan depends on this.

Six request types, in roughly priority order:

If the request is ambiguous, ask one clarifying question via AskUserQuestion. Do not guess.

Step 1: Inspect the workspace

Gate: does the request already name an exact, unambiguous source? A URL, or an exact file path, resolves the source completely — there is nothing left to discover about where the artifact is. In that case do NOT run a general workspace inventory. Instead:

1. Derive the candidate slug from the named source (the URL/file's own filename: it-ops-starter-semantic-blueprint.md → it-ops-starter; related_modules/other metadata is not needed for this, just the filename stem).
2. Run ONE targeted exact-filename existence check against the convention folders only — test -f semantius/blueprints/<slug>-semantic-blueprint.md / semantius/specs/<slug>-semantic-spec.md. Exact filename, never a glob, never a substring/prefix/suffix match. A file is either named it-ops-starter-semantic-blueprint.md and is the artifact, or it is named anything else (v0-it-ops-starter-semantic-blueprint.md, it-ops-starter-v2-semantic-blueprint.md, my-it-ops-starter-semantic-blueprint.md) and is not a match — full stop, it does not get read, opened, cmp'd, or mentioned. A blueprint's name is its filename; *<slug>* glob matching treats "contains the slug as a substring" as "is the artifact," which is exactly backwards — it pulls in prefixed/suffixed variants nobody named and burns a read-and-compare cycle on each one. If the exact-name file is absent, that's a miss: proceed to Step 2 (fetch the named URL) or build fresh, same as if the workspace were empty. Do not fall back to searching for "something close."
3. Do not run the legacy root-level scan at all for a named-source request. Root-level legacy placement is a migration-era concern for artifacts nobody named explicitly; it has no bearing on a request that already says exactly what to fetch and deploy. If the user separately mentions a root-level file by name, that's a named source too and step 2's exact-filename check (pointed at root instead) covers it — still not a scan, still exact-match only.

Only when the request does NOT name an explicit source (status checks, "what's deployed", a bare "deploy this" with nothing else in the workspace to disambiguate, onboarding) does a general inventory make sense, because there IS something to discover — which artifact, if any, the vague request could mean:

# Primary location (the convention): semantius/blueprints/ and semantius/specs/
find semantius/blueprints semantius/specs -maxdepth 1 -name '*.md' 2>/dev/null

# Legacy locations: blueprints/specs left at the workspace root by older runs.
# Still scope this to any slug hints the request text does contain (e.g. "the ATS
# blueprint" → scope to *ats*), never a blanket `*-semantic-blueprint.md` glob —
# that pulls every unrelated file at the repo root into consideration for zero
# benefit. Only fall back to the fully unscoped glob when the request truly gives
# no slug hint at all (rare: "what's sitting in my workspace root?").
find . -maxdepth 1 -name '*-semantic-blueprint.md' -o -name '*-semantic-spec.md' 2>/dev/null

1.1 Locate artifacts in place, and COPY (never move) the deployed artifact into the convention folder

Per INV-2, the skill reads artifacts wherever they are and copies (never moves) the deployed artifact into the convention folder. The mechanics for every deploy:

• Copy up front, with cp, before any edit. As soon as a root-level artifact is resolved for this run, copy it into semantius/blueprints/ or semantius/specs/ (created on demand with mkdir -p) immediately, before the customize / extend / rebuild pass or the analyst runs. The convention-folder copy becomes the working path: every edit targets it, so it still matches exactly what was deployed; the root original is read once and never modified (editing it is a bug).
• Existing differing convention copy: if a convention copy of this slug already exists and differs from the root, resolve via the "Slug present in BOTH" widget below first, then make the chosen version the working copy. Never blind-overwrite.
• If the resolved artifact already lives in the convention folder, it is already the working path; nothing to copy.

The ban is specifically on moving and deleting files the skill did not create (a filename pattern is NOT proof of ownership). A non-destructive copy of the single artifact this run deploys is required and expected; never scan-and-move or scan-and-delete pre-existing files.

Slug present in BOTH root and the convention folder. Pick which copy to read for this request. Never move or overwrite either file as a result.

• Unrelated file (not part of this request): leave both copies untouched, log to $DIAG_LOG, say nothing in chat. Do not pick a winner, do not mention it. The failure mode to avoid: announcing a real-estate-agent collision while the user asked to deploy hiring-starter, then admitting "(this is unrelated to your request)". If it's unrelated, it does not belong in chat at all.
• The artifact being deployed: the two copies may differ, and reading the wrong one is a real risk, so do NOT silently pick. Compare them with cmp -s:
  • Byte-identical: no ambiguity. Read the convention-folder copy, log to $DIAG_LOG, continue without asking.
  • Different: fire the collision widget below and let the user choose which to read. This applies equally to blueprints (root vs semantius/blueprints/) and specs (root vs semantius/specs/).

Collision widget (only when the deployed artifact's two copies differ):

• question: "There are two different copies of <slug>, one in the workspace root and one in the convention folder. Which should I use for this deploy?"
• header: "Which copy"
• options:
  1. "Convention-folder copy (Recommended)" — "Use the copy in the convention folder (the standard location). Last changed <date>."
  2. "Root-folder copy" — "Use the root-level copy instead. It stays exactly where it is; nothing is moved or overwritten. Last changed <date>."

Surface each copy's last-changed date in the option descriptions so the user can tell which is newer. Whichever the user picks, read that copy and leave BOTH files exactly where they are. This disambiguation is a one-off, NOT standing policy; do not write it to customizations.yaml, a future collision asks again.

After 1.1, blueprints and specs are read wherever they live (convention folder or repo root); nothing has been moved. Step 1.2 (workspace summary) reads from both locations.

1.2 Workspace summary

A slug may live in the convention folder, at the repo root (legacy), or both; the skill reads it wherever it is and never moves it (per 1.1). When the same slug appears in both locations, prefer the convention-folder copy as a defensive fallback for the summary, unless the user picked the root copy via the 1.1 collision widget.

For each candidate file, read only the front-matter (the first 30 lines is enough). Extract:

• artifact (semantic-blueprint vs semantic-spec)
• blueprint_version (blueprints) or version (specs)
• system_slug
• reconciled_at and source_blueprint (specs only)

Build a workspace summary:

Workspace artifacts:
  semantius/blueprints/
    - ats-candidate-crm-semantic-blueprint.md  (artifact: semantic-blueprint, blueprint_version: "2.0", slug: ats-candidate-crm)
  semantius/specs/
    - ats-candidate-crm-semantic-spec.md       (artifact: semantic-spec, version: "4.1", slug: ats-candidate-crm, reconciled 2026-05-25)

If the request mentions a URL, plan to fetch it first (Step 2).

If the request mentions a specific file by path or name, prefer that over auto-discovery. When the location the user names doesn't match where the file actually is (e.g. they say "from the root folder" but the only match lives in semantius/blueprints/), just use the unambiguous match silently. Do NOT narrate a paragraph explaining the discrepancy; the user named the artifact, not the path, and a location correction is housekeeping for $DIAG_LOG. Surface a one-line clarification only if there are genuinely two candidates and you had to pick.

The workspace summary itself is internal: it goes to $DIAG_LOG, not chat. The user does not need a front-matter dump (blueprint_version, entity counts, "reconciled" dates) before the plan. Lead the chat with the plan, not with an inventory. Exception: 1.3 below. When an existing workspace artifact matches the user's request, that match MUST be surfaced before the plan is built. The "no inventory dump" rule covers unrelated artifacts; it does NOT cover a slug-match on the thing the user just asked for.

1.3 Match check: surface pre-existing artifacts that could satisfy the request

Before constructing any plan, the admin checks whether the workspace already contains a blueprint or spec that could satisfy the user's request. If it does, the admin MUST tell the user and let them choose between deploying the existing artifact, starting over, or auditing it first. Silently building a new blueprint when a matching one already exists, or silently routing the deploy through an existing spec the user didn't know about, is the failure mode this section closes.

Exception: exact-source bypass — skip the widget entirely. The widget above exists to resolve ambiguity about which artifact the user meant. There is no ambiguity, and the widget must NOT fire, when both of the following hold:

1. The request names an exact, unambiguous source: a URL, or an exact file path/name. (Inferred matches from slug/keyword similarity, per the "What counts as a match" tests below, do NOT qualify — those are exactly the ambiguous case the widget is for.)
2. The workspace already has a blueprint or spec for that source, and it is confirmed byte-identical to the named source (fetch it — Step 2 — and cmp -s it against the workspace copy per Step 1.1's comparison) or, for a spec, the workspace spec's source_blueprint reconciles a byte-identical blueprint and was reconciled on or after that blueprint's current content.

When both hold, there is nothing to decide: the workspace artifact is the thing the user asked for, byte-for-byte, already reconciled. Log the match to $DIAG_LOG and go straight to the plan (deploy the existing spec through the modeler if one is current; otherwise blueprint → analyst → modeler). Asking "what do you want to do?" about a file that is a verified exact match of what was explicitly requested is not resolving ambiguity, it's manufacturing it, and it wastes the user's time. If the fetched source differs even slightly from the workspace copy, the exception does not apply, fall through to the normal match-check widget (the difference is real ambiguity: did the user want the update applied, or did they mean to keep what's there?).

What counts as a match. Walk every blueprint and spec in the Step 1.2 workspace summary and apply the following tests against the user's request text:

1. Slug match. Derive a candidate slug from the user's request (e.g. "roadmap planner" → roadmap; "ATS for our recruiting team" → ats, recruiting, ats-candidate-crm). Any artifact whose system_slug equals a candidate slug, or whose system_slug is a substring/superstring of one, is a match candidate.
2. System-name match. Any artifact whose system_name (case-insensitive, ignoring filler words like "and", "the", "for") shares two or more content words with the user's request is a match candidate. Example: request "product roadmap planner" matches system_name: Product Roadmap on both product and roadmap.
3. Tagline / description match. Any artifact whose tagline shares a notable verb phrase with the request (request "collect ideas and defects, prioritize them" vs tagline "Capture ideas and defects, prioritize them, and build a release plan") is a match candidate.

A request can produce zero, one, or many match candidates. All must be surfaced, none silently picked.

What to do on a match. Fire AskUserQuestion BEFORE any sub-skill is invoked and BEFORE the plan is built. The question shape:

• question: "I found <file> in your workspace that looks like it already covers your request (slug <slug>, <system_name>). What do you want to do?"
• header: "Existing artifact"
• multiSelect: false
• options (in this order):
  1. label "Deploy the existing <blueprint|spec> (Recommended)", description: "Use <file> as-is. Skip building a new one. Pipeline: <analyst → modeler for a blueprint match; modeler for a spec match>."
  2. label "Audit / review the existing artifact first", description: "Run an audit pass on <file> so you can see what's in it before deciding. No writes to your semantic model."
  3. label "Start over (build new)", description: "Ignore <file> and build a fresh design from scratch. You'll be asked where to move the existing file so it isn't accidentally re-used (the admin never deletes a file it didn't create)."
  4. label "Cancel", description: "Stop without doing anything."

Multiple match candidates. When the workspace has more than one matching artifact (e.g. both a blueprint and a spec for the same slug, or two distinct slugs that both could be what the user meant), enumerate them in the question body and let the user pick which one to act on (AskUserQuestion with one option per candidate plus "Start over" and "Cancel"). Never silently pick "the newer one" or "the one that matches more closely" — picking is the user's decision.

On option 3 (Start over). Fire a follow-up AskUserQuestion asking where to move the pre-existing artifact: an archive folder (semantius/archive/), a user-specified path, or "leave in place and I'll rename my new build's slug to avoid the collision." The admin never deletes pre-existing files (per the rules at the bottom of this SKILL); it can only move them, and only with explicit user direction.

On option 1 / 2. Skip Step 0's classification result and route directly to the appropriate pipeline (deploy through Step 6 for option 1; architect Audit or analyst Audit for option 2). The user's choice here overrides whatever Step 0 originally classified the request as.

Run this check between inspection and planning, never after the plan is built, so the plan is built from the user's informed choice. A match check fired after planning is too late: the plan's narrative already contradicts what's about to happen.

The "no inventory dump" rule still holds for unrelated artifacts. A workspace cluttered with old blueprints from prior unrelated work does NOT trigger this widget. Only artifacts whose slug, system_name, or tagline matches the current request surface here. Everything else stays internal per Step 1.2.

Step 2: Fetch remote artifacts (only when input is a URL)

When the user gives an http(s):// URL, fetch it before any other step using the canonical fetch-validate-place procedure in Step 6.1: curl -s -L into .tmp_admin/<run_id>/incoming/, validate the first 30 lines parse as front-matter with a known artifact: value, then move to semantius/blueprints/<system_slug>-semantic-blueprint.md or semantius/specs/<system_slug>-semantic-spec.md (folders created on demand). Never WebFetch (INV-6).

On any fetch failure (curl non-zero exit, empty file, no front-matter, unknown artifact: value), halt and report the failure verbatim; do not guess. The semantius/ folder at the workspace root is the committed home for these artifacts (distinct from the plugin install, which lives in the user's Claude Code plugin folder, not their project repo).

Step 3: Plan the pipeline

Given the request type from Step 0 and the workspace state from Step 1/2, decide which sub-skill(s) to invoke and in what order.

Decision table

Why everything-deploy routes through Step 6: one item or many, the pipeline is the same. Step 6 has the customize/deploy flag plumbing, the customizations-file handoff, the unified report. Greenfield builds and catalog clones also route through Step 6 for the analyst → modeler half and the unified report, but they carry NO customize / review / deploy questions: the architect's Create pass already covered design and deploy is implied (see "Greenfield and clone builds skip scope flags"). The only request types that bypass Step 6 are pure-architect operations (Audit on a blueprint), pure-analyst operations (Audit on a spec), and admin-only operations (status, backup, health). Anything that ends in writes to the live semantic model goes through Step 6.

Resolve scope flags before presenting the plan

Scope flags are resolved before any plan that contains them is rendered (INV-3). They are routing decisions, not confirmations: customize=yes makes a blueprint architect → analyst → modeler, customize=no makes it analyst → modeler, so a plan cannot be correct until they are resolved. Greenfield builds and catalog clones short-circuit (no scope question fires; the bug guard: "create a task list" must NEVER produce "Deploy the task-list design as designed, or edit it first?"). For an existing artifact (a workspace file, a Step 1.3 match, or a URL fetched in Step 2):

• Single identified artifact (one named file, one fetched URL, one Step 1.3 match): resolve its flags HERE, before the plan is rendered. The front-matter (system_name) is in hand, so the question wording is fully formed.
• Multi-source / glob (items only enumerated in Step 6.1): resolve each item's flags in Step 6.4, still before that item's plan line is rendered in Step 6.6.

Use the inference-then-ask procedure in Step 6.4 (intent table 6.4.1, exact wording 6.4, procedure 6.4.2); do not re-derive it here. These are scope questions, not the deploy confirmation, so INV-1 never suppresses them: a bare "deploy this" leaves customize at ? and MUST fire the customize question.

Presenting the plan

By this point the scope flags are resolved, so the plan reflects them and shows the right number of steps. Pipeline flows (build, clone, deploy) do NOT render-and-run their plan here — they hand off to Step 6, which renders the runnable plan in Step 6.6 after Step 6.4 resolves each item's flags. Step 3 renders a runnable plan only for flows that bypass Step 6 (audit, admin). Never render a deploy plan and jump straight to spawning a sub-skill from Step 3: that skips Step 6.4.

Render per INV-1 (informational; no up-front Proceed? gate; the modeler is the single write gate) and INV-5 (markdown prose, never code-fenced). The full plan-line authoring rules, the four plan patterns (read-only / write-bound / network-fetch / greenfield), and the worked multi-item examples are in references/plan-shapes.md. The canonical write-bound shape:

Plan:

1. Match ats-candidate-crm against your live semantic model and write the spec.
2. Apply ats-candidate-crm to your live semantic model.

Step 1 is the spec-building step: it produces the deployable spec file and asks you a few merge / reuse / promote questions; it doesn't touch your live model. Step 2 applies that spec; the modeler shows what it will change and asks a final yes/no before it updates the live model.

Then run the pipeline; the modeler is the single write gate (INV-1). If the user wants to change scope or stop after seeing the plan, they say so in chat; re-resolve the flags (Step 6.4) and re-render, or stop cleanly ("Cancelled. No changes made."). Nothing has run, and the modeler still gates every write, so no unintended write can slip through.

Step 4: Execute the pipeline

For each step in the plan, run the corresponding sub-skill inline in the main thread (load and follow its SKILL.md in this same conversation context) so its AskUserQuestion prompts reach the user directly.

All three pipeline sub-skills are interactive, so all three run inline. The architect's customize pass is an interactive edit loop only the user ends; the analyst fires the merge / reuse / promote / collision questions during reconciliation; the modeler asks its pre-execute yes/no before every write. Never spawn an interactive sub-skill as an Agent-tool subagent: a subagent runs in an isolated context and cannot conduct these dialogs, so its questions would never reach the user and the pipeline would stall or guess. Reserve the Agent tool for genuinely non-interactive helper work only — none of the architect / analyst / modeler pipeline steps qualify.

Sub-skill invocation pattern

For each step:

1. Pre-flight: confirm the input artifact exists at the expected path.
2. Invoke inline: establish the run context (Step 7.3) in the conversation, then enter the sub-skill in this same context and follow its SKILL.md. Let its AskUserQuestion prompts surface to the user; answer nothing on the user's behalf. The sub-skill produces its output artifact.
3. Verify: confirm the expected output artifact appeared in the workspace at the expected path.
4. Surface: tell the user the step succeeded, with a one-line summary (output path, key metrics).

If any sub-skill halts, surfaces an error, or asks the user a question the admin can't answer on its behalf, stop the pipeline at that point and surface the sub-skill's last message verbatim. The admin does not try to recover or guess.

Common sub-skill triggers (so the admin invokes them correctly)

Versioned input gates

Each sub-skill enforces its own version contract on input. The admin trusts those gates — it does not pre-check versions. If a sub-skill rejects input as a version mismatch, surface the rejection message verbatim.

Step 5: Admin-only operations

Operations that don't involve the architect / analyst / modeler chain. The admin executes these directly via use-semantius (CLI patterns) without spawning sub-skill agents. Full procedures (the exact Status output template, the backup JSON shape, the listing wrappers, and the health probe) live in references/admin-operations.md; load it when running one of these.

Get started (5.5) stays resident below: it is a top-level request type (Step 0) with its own onboarding flow.

5.5 Get started (onboarding)

Get started — the front door for someone new to the platform. It makes sure the tooling is in place, verifies the connection by querying the live database, reports how much is already deployed, and points to the blueprint catalog so the user can stand up a data platform tailored to them. Safe to run anytime; triggered by "get started", "I'm new here, set this up", and the like (no external command required).

Flow:

1. Run the shared preflight (references/preflight.md). This is the install check: it installs the semantius CLI, Bun, jq, and yq if any are missing (Windows / macOS / Linux), and configures .env auth (asking for the API key when needed). On success the active org and ui_baseurl are in hand. If a guard halts (org is adenin, a tool could not be installed, the API key was not supplied), surface that and stop — there is nothing to get started against until the platform is reachable.

2. Verify the connection by querying the database. Confirm the catalog actually reads back, not just that the CLI authenticated:

   semantius call crud read_entity '{"slug": "users"}'   # a known built-in must read back
   semantius call crud read_module '{}'                  # the deployed modules
   

   If either errors, s

…(truncated)