# Semantius Admin > Orchestrates the Semantius pipeline (`semantius-architect`, `semantius-analyst`, `semantius-modeler`) and handles instance administration. **Trigger when intent spans more than one skill, on a remote blueprint URL, or on "deploy this blueprint", "deploy these blueprints", "deploy all of these", "set up these systems", "build me a system and deploy it", "set up a CRM end-to-end", "clone the candidate-crm blueprint and deploy", "what's deployed in our instance?", "status of semantius", "audit this file" (naming no specific skill), "back up the catalog", "snapshot the module", "get started", "I'm new here, set this up", or anything needing workspace artifacts inspected and routed to the right sub-skill.** Also trigger on a deploy request with multiple URLs, paths, or a glob. Do NOT trigger when the user invokes one sub-skill directly (not "audit this spec with semantius-analyst", not "run the modeler"); let those through. Front door for end-to-end and ambiguous requests, not a wrapper on Semantius calls. - Skill: `semantius/semantius-admin` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add semantius/semantius-admin` - Raw SKILL.md: https://api.skillmd.com/api/skills/semantius/semantius-admin/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: semantius (https://skillmd.com/u/semantius) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/semantius/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`](./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//diag-.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`](./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`](./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: | Type | Trigger phrases | Pipeline | |---|---|---| | **Get started / onboarding** | "get started", "I'm new here, set this up", "what can I build?" | admin-only (Step 5.5): run preflight (install check) → verify the connection by querying the database → count deployed modules → point to the blueprint catalog | | **End-to-end build** | "build me a CRM and deploy", "set up an ATS end-to-end", "I need a helpdesk live in our instance" | architect → analyst → modeler | | **Clone-and-deploy** | "clone the candidate-crm blueprint and deploy", "use ats-candidate-crm as a starting point and deploy", "deploy a copy of the X blueprint" | architect (Catalog-Clone) → analyst → modeler | | **Deploy existing artifact** | "deploy this blueprint", "deploy https://...md", "deploy the file in my workspace" | (fetch if URL) → analyst (if blueprint) → modeler | | **Inspect / audit / status** | "what's deployed?", "status of semantius", "audit this file" | admin-only (no sub-skill chain), or routes to the right Audit mode | | **Admin operation** | "back up the catalog", "snapshot module X", "list modules", "rotate API key" | admin-only (operates directly via use-semantius) | 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/-semantic-blueprint.md` / `semantius/specs/-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; `**` 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: ```bash # 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 ``, 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 ``."* 2. `"Root-folder copy"` — *"Use the root-level copy instead. It stays exactly where it is; nothing is moved or overwritten. Last changed ``."* 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 `` in your workspace that looks like it already covers your request (slug ``, ``). What do you want to do?"* - **header**: `"Existing artifact"` - **multiSelect**: `false` - **options** (in this order): 1. label `"Deploy the existing (Recommended)"`, description: *"Use `` as-is. Skip building a new one. Pipeline: ."* 2. label `"Audit / review the existing artifact first"`, description: *"Run an audit pass on `` so you can see what's in it before deciding. No writes to your semantic model."* 3. label `"Start over (build new)"`, description: *"Ignore `` 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//incoming/`, validate the first 30 lines parse as front-matter with a known `artifact:` value, then move to `semantius/blueprints/-semantic-blueprint.md` or `semantius/specs/-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 | Request type | Workspace state | Plan | |---|---|---| | End-to-end build | Empty workspace | `architect (Create-Greenfield)` → analyst → modeler. **No scope-flag questions fire** (no `customize`, no `review`, no `deploy` ask): the architect's interactive Create pass IS the design, and `deploy` is implied by the build request. The created blueprint becomes Step 6's item; the modeler's own pre-write yes/no is the single gate. See "Greenfield and clone builds skip scope flags" below and Pattern 4. | | End-to-end build | Blueprint present, no spec | **First run Step 1.3 match check.** If the blueprint matches the request, the user's choice at 1.3 routes the run (deploy / audit / start-over). If 1.3 found no match (the workspace blueprint is unrelated), hand off to Step 6 with the workspace blueprint as the only item ONLY when the user's request is explicitly about that blueprint; otherwise treat as Empty workspace. **Never silently use a workspace blueprint the user didn't reference.** | | End-to-end build | Spec present | **First run Step 1.3 match check.** If the spec matches the request, the user's choice at 1.3 routes the run (deploy / audit / start-over). If 1.3 found no match (unrelated spec), treat as Empty workspace and run greenfield architect. **Never silently use a workspace spec the user didn't reference.** | | Clone-and-deploy | Empty workspace | `architect (Create-Catalog-Clone)` → analyst → modeler. Like greenfield, the architect creates the artifact, so **no scope-flag questions fire**; `deploy` is implied. The cloned blueprint becomes Step 6's item. | | **Deploy existing** | **Any (1 or N blueprints/specs)** | **Hand off to Step 6.** This is the universal deploy path regardless of how many items. Scope flags (`customize` / `review`, plus `deploy`) are resolved FIRST per "Resolve scope flags BEFORE presenting the plan" below (inference in 6.4.1, asked when ambiguous), so a bare "deploy this" still fires the customize question before anything runs. | | Audit | Blueprint named | `architect (Audit)` on the blueprint (does NOT route through Step 6). | | Audit | Spec named | `analyst (Audit)` on the spec (does NOT route through Step 6). | | Audit | Both, no name | Ask user which to audit, or audit both serially. | | Status | n/a | Admin-only (Step 5). | | Admin (backup, list, ...) | n/a | Admin-only (Step 5). | **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`](./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) | Sub-skill | Invoke when | Input artifact | Output artifact | |---|---|---|---| | `semantius-architect` | Building a new blueprint, cloning a catalog blueprint, or auditing/extending/rebuilding an existing blueprint | (none, or `-semantic-blueprint.md` for Audit/Extend/Rebuild/Customize modes) | `-semantic-blueprint.md` | | `semantius-analyst` | Reconciling a blueprint against live catalog into a deployable spec | `-semantic-blueprint.md` | `-semantic-spec.md` | | `semantius-modeler` | Deploying a reconciled spec | `-semantic-spec.md` | (live catalog mutations) | ### 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`](./references/admin-operations.md); load it when running one of these. | Operation | Trigger | What it does | |---|---|---| | **Status** (5.1) | "what's deployed?", "status of semantius" | Show workspace artifacts and live modules (entity / permission counts, last deploy). Read-only. | | **Backup** (5.2) | "back up the catalog", "snapshot module X" | Dump the live model (optionally one module) to `semantius-backup-.json`. Read-only. | | **Listing** (5.3) | "list modules / entities / permissions / users / roles" | Convenience read wrappers producing readable tables. Read-only. | | **Health** (5.4) | "check the connection" | Probe `getCurrentUser`, read a known built-in, report OK / FAIL. | 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`](./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: ```bash 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)