---
name: setup
description: Verify GRCITSM tenant setup — MCP catalog, tenant pin + write permissions, working dirs, bulk-write workflow; doctor checklist on re-run
---

# setup

One-command project setup for the `grcitsm-analyst` plugin. Run this once per project after registering the `grcitsm` MCP server (see SETUP.md). It verifies the tenant connection, settles which tenant this project writes to and permits the calls a write run makes, and scaffolds the working directories. It doubles as a doctor: re-run it any time and it reports ✓ or a one-line fix per check, changing nothing on a healthy project. The bulk-write workflow needs no install — the plugin ships `halo-apply.js` and Claude Code auto-surfaces it as the invocable `grcitsm-analyst:halo-apply`, so there is nothing to copy or refresh on plugin updates.

## Agents

| Agent | Purpose | When Invoked |
|---|---|---|
| (none) | This command runs inline checks and file operations directly; no agent delegation. | — |

Perform these steps in order, then report a single consolidated checklist.

## 1. Server registration

Check whether a GRCITSM MCP connection is available in this session. The supported configuration is the claude.ai OAuth connector named starting with `GRCITSM` (its tools appear as `mcp__claude_ai_GRCITSM__CF_<tool>`, or with a suffixed variant like `mcp__claude_ai_GRCITSM_Dev__…`); a manually registered server named `grcitsm` (`mcp__grcitsm__CF_<tool>`) also works. Use ToolSearch with a query like `+grcitsm asset` to probe for the server's tools.

- If no GRCITSM tools are found at all: report that no connection is available and give the user both connection paths — (a) recommended: add the tenant MCP endpoint as a claude.ai connector (Settings -> Connectors), **named starting with `GRCITSM`** per SETUP.md, or (b) alternate: register the tenant MCP endpoint under the name `grcitsm` in `.claude/settings.json` or `.claude/settings.local.json`. Adding or registering the connection is the one step the user must always do by hand — stop here and do NOT scaffold directories or install the workflow until the server is present. Note: connector OAuth consent does not run headlessly — for scheduled/headless runs, complete the consent in-app first so a token is stored.
- If tools are found under a server name outside those two shapes (the same `CF_*` tool names on some other server): report the mismatch and the actual name found. The plugin's skills reference tools by bare name, so a differently-named server still works, but a `GRCITSM`-prefixed connector (or `grcitsm` server) is the supported configuration. Continue with the rest of setup.

## 2. Tool catalog coverage

Read `reference-docs/required-mcp-tools.md` (in this plugin) for the full required tool list. Using ToolSearch, verify each tool group is present — probe at minimum one tool per group, and probe ALL of these critical tools individually:

- `get_asset`, `asset_summary`, `update_asset`, `create_asset`, `asset_types`, `asset_type_fields`
- `get_ticket`, `create_new_ticket`, `update_ticket_fields`, `agent_note`
- `system_information`, `update_system_information`
- `baseline_catalog`, `lookup_controls`, `lookup_requirements`
- `reconcile_ssp_assets`, `set_asset_relationships`

Also probe the optional template pair `ticket_templates` + `apply_ticket_template` (soft check — NOT critical): if present, report template-aware creation as available; if absent, note that agents skip the template check silently and fall back to `create_new_ticket`. An absent pair is never a setup failure.

List any missing tools by name. Missing tools mean the tenant's MCP tool catalog is incomplete — surface the missing tool names to the operator who provisioned the tenant for remediation.

## 3. Live connectivity check

If the catalog is present, make one cheap read call to confirm the connection works end to end: call `system_information` (no arguments or default arguments). Report whether it returned data, and if so, which system(s) the tenant exposes (system name + impact level — do not dump the full payload).

## 4. Pin & permit the tenant

This step makes write runs just work: it settles WHICH tenant this project targets, and pre-approves the calls a write run makes so nothing interrupts it mid-flight. On the default client setup — a single connector named `GRCITSM` — it asks nothing and writes no pin file.

**Already wired?** Check before doing any work. If `.claude/grcitsm-tenant.json` exists, confirm its prefix's tools are visible in this session's catalog and that the verification read below succeeds under it; a healthy pin is kept as-is, never re-pinned. Read `.claude/settings.local.json` and check whether `permissions.allow` already carries the three rules below. Anything already in place is reported ✓ and left untouched; only the missing pieces are proposed.

**Pin — the exception, not a prerequisite.** Enumerate the GRCITSM connectors this session holds using the same ToolSearch probe as step 1; the session's own tool catalog is the source, so this works in claude.ai sessions where no `claude` CLI exists. Collect the candidate prefixes whose server segment carries `GRCITSM` as a delimited token (`mcp__claude_ai_GRCITSM_Dev__CF_get_asset` → `mcp__claude_ai_GRCITSM_Dev__`), then:

- **Sole candidate, default-named `mcp__claude_ai_GRCITSM__`** → nothing to pin. Every write run resolves this by itself, so a pin file would add a stale-config risk for no gain. Verify it (below) and report the project as running in default mode.
- **Sole candidate, some other name** → offer to write the pin so the name is sticky across sessions.
- **Several candidates** → list them, ask the user which tenant THIS PROJECT targets, and write the pin for their pick. Never pick for them. This is the case the pin file exists for.
- **None, and the default does not verify** → stop with the step-1 registration guidance.

Verify with one live read before pinning or reporting anything healthy: call `<prefix>CF_client_details` (no arguments) and confirm the returned client catalog has at least one row. A tenant you cannot read is not a tenant you may write, and a pin you cannot read is not a pin — if the read fails, report the failure and write nothing. The pin file, when one is warranted, goes in the project at `.claude/grcitsm-tenant.json`:

```json
{"prefix": "mcp__claude_ai_GRCITSM_Dev__", "pinned": "2026-08-08"}
```

**Permit.** Show the user the exact rules below, then **with their explicit confirmation** add them to the project's `.claude/settings.local.json` under `permissions.allow`:

```json
{
  "permissions": {
    "allow": [
      "mcp__claude_ai_GRCITSM",
      "Bash(*resolve-tenant-prefix.sh *)",
      "Bash(python3 *pipeline.py *)"
    ]
  }
}
```

- The bare server name (no tool segment, no glob — the server segment must be literal) pre-approves every tool on that connector. `mcp__claude_ai_GRCITSM` is the default-name rule and is therefore static, so a client repo template may ship it already checked in; a differently-named connector gets its own rule written at pin time. Either way list **one server only** — the tenant this project targets. Other GRCITSM connectors stay unlisted, so an accidental cross-tenant call still prompts. That is a tenant guard, not friction.
- The two Bash rules cover the helpers every apply run shells to (`resolve-tenant-prefix.sh` and `pipeline.py`).
- Merge into an existing `settings.local.json` if one is present — read it first, append to `permissions.allow`, never clobber other entries.

This is user-consented, setup-time configuration written by the main session, which is the one sanctioned place permissions are granted. It is exactly what agents are forbidden to do for themselves mid-run: a blocked tool during a write run is a failure to report, never something to route around by editing an allow-list.

**Report.** State the mode — default `GRCITSM`, no pin needed, or pinned to `<prefix>` — name the tenant from the client catalog just read, and say that write runs will not prompt. Caveat: an organization-level connector policy set to `ask` overrides these allow rules; the prompts still appear and only an org admin can change that.

Re-run `/grcitsm-analyst:setup` to re-pin when the project should target a different tenant.

## 5. Scaffold working directories

The pipelines read from `inputs/` and write to `outputs/`. Create either if missing in the project root — just create them, no need to ask:

```bash
mkdir -p inputs outputs
```

Per-run state (action files, progress/checkpoint ledgers) lives under each run's own folder at `outputs/<run>/state/`, created at run time — there is no top-level `state/` directory. Report which dirs were created vs already present.

## 6. Confirm the bulk-write workflow is available

The apply loop for the `halo-action-pipeline` is driven by the plugin's frozen `halo-apply` workflow. **No copy into the project is required** — the plugin ships `workflows/halo-apply.js` and Claude Code auto-surfaces it as the invocable `grcitsm-analyst:halo-apply`, running the plugin's own engine at the active version. There is nothing to install on first run and nothing to refresh after a plugin update; the single source of truth is the plugin.

Optionally confirm it is visible in this session: the invocable `grcitsm-analyst:halo-apply` should appear in the available skills/commands list (its description starts "Apply a halo-action-pipeline action file in dependency order via executor agent waves"). If present, the apply loop is ready. This is never a failure: even with the workflow absent, bulk writes fall back to a main-thread apply loop — the workflow only adds deterministic round-driving for large (40+ action) writes.

## Output format

A compact checklist. Every line is either ✓ (already true — nothing was changed) or FIX with the single action that closes it. Setup is a doctor as much as an installer: run it on a healthy project and it prints all ✓, asks nothing, and writes nothing.

- **Server registration** — ✓ `grcitsm` present / found as `<other name>` / FIX: not registered, see SETUP.md
- **Tool coverage** — ✓ N of M critical tools present / FIX: name the missing tools for the tenant operator
- **Live connectivity** — ✓ system(s) exposed (name + impact level) / FIX: the read failed, re-authenticate the connector
- **Tenant** — ✓ default `GRCITSM`, no pin needed (tenant `<client name>`, verified) / ✓ pinned to `<prefix>` via `.claude/grcitsm-tenant.json` (tenant `<client name>`, verified) / FIX: several connectors or a non-default name, pin it (step 4)
- **Permissions** — ✓ all three allow rules present in `.claude/settings.local.json` / FIX: add the missing rules (step 4, needs your confirmation) / declined by the user
- **Working directories** — ✓ `inputs/` + `outputs/` present / created now
- **Bulk-write workflow** — ✓ `grcitsm-analyst:halo-apply` available (no install needed) / not surfaced (main-thread fallback applies, never a failure)

Offer to apply every FIX in one pass; the permissions fix still needs explicit confirmation. End with either **"Ready"** or the specific next step to fix (most commonly: register the `grcitsm` MCP server per SETUP.md).
