---
name: grcitsm
description: Router and workflow primer for the grcitsm Halo MCP tool catalog — the mandatory create → update chains, ticket-type → tool routing, pre-update lookups, and where every piece of platform and tenant doctrine lives (vendored halo-platform corpus, ticketing doctrine, tenant catalog). Load before composing any Halo MCP tool call.
---

# grcitsm — Halo MCP workflow router

Workflow doctrine for the grcitsm Halo MCP catalog. **The MCP tool descriptions are the source of truth for what each tool does and how to call it** — this skill stays DRY by not repeating any of that. The doctrine itself lives in three layers; this skill routes to them and carries only the rules you need before your first call.

## References

| Reference | Type | Location | When to Use |
|---|---|---|---|
| `write-semantics.md` | File | `reference-docs/halo-platform/write-semantics.md` | **Before ANY write** — null-handling per tool, lookup rules, framework-CF ordering, payload cliff, who-fields, verify-every-write, KB API, anti-patterns |
| `api-mcp-semantics.md` | File | `reference-docs/halo-platform/api-mcp-semantics.md` | Tool families, relay semantics ("Task queued."), read-tool caps + staging, SLA-scoped priority labels |
| `data-model.md` | File | `reference-docs/halo-platform/data-model.md` | Table domains, naming gotchas, JOIN patterns, dual role model, ticket/asset taxonomy, relationship ids |
| `sql-dialect.md` | File | `reference-docs/halo-platform/sql-dialect.md` | Any SQL: the no-ORDER-BY rule, MindsDB dialect, probe-first CF rule |
| `ssp-narrative-doctrine.md` | File | `reference-docs/halo-platform/ssp-narrative-doctrine.md` | By-who taxonomy, inheritance rules, status vocabulary |
| `grcitsm-ticketing.md` | File | `reference-docs/grcitsm-ticketing.md` | Template-driven creation (check → ask → apply), create→update chain detail, cross-client creation, ticket-type routing, hierarchies, KSI Validation tree, Validation rows, compositions |
| `grcitsm-tenant-catalog.md` | File | `reference-docs/grcitsm-tenant-catalog.md` | Catalog at a glance, ticket-side CF id catalog, diagnostic workflow |
| `halo-agent-role-model.md` | File | `reference-docs/halo-agent-role-model.md` | Dual role model rules + per-tenant refresh SQL for role/POC work |
| `required-mcp-tools.md` | File | `reference-docs/required-mcp-tools.md` | Full required tool list for tenant catalog coverage |
| `ssp` | Skill | `plugins/grcitsm-analyst/skills/ssp/` | SSP asset spine workflow primer |
| `halo-bulk-update` | Skill | `plugins/grcitsm-analyst/skills/halo-bulk-update/` | Any operation touching >20 rows |
| `halo-ssp-asset-write-conventions` | Skill | `plugins/grcitsm-analyst/skills/halo-ssp-asset-write-conventions/` | SSP asset write rules incl. AFUUID conventions |
| Context7 docs connector | MCP | `resolve-library-id` → `query-docs` | Halo product/feature/how-to questions the vendored corpora don't answer |
| GRCITSM product documentation | URL | `https://grcitsm.stratuscyber.com/` | GRCITSM-specific implementation questions |
| Halo guides | URL | `https://www.usehalo.com/guides/2338` | General Halo product guides |

> `reference-docs/halo-platform/` is a **vendored shared corpus** — byte-identical across plugins, refreshed by sync. Never hand-edit it here.

## When to use this skill

Load before composing any Halo MCP tool call: creates, updates, lookups, reads; prompts mentioning ticket creation/update, agent note, POA&M, deviation, KSI validation, Strategic Value, priority/status/target-date changes; "which Halo tool?" disambiguation.

## The rules you need before the first call

0. **Template check before any net-new create.** When a create request plausibly matches a recurring/structured intent (onboarding, user access request, a training project — illustrative only; enumerate live via `ticket_templates`), call `ticket_templates` first, present matching parent templates (`Ticket Template` rows only — name, ticket type, to-do count, Creates a Project?) and ASK before applying via `apply_ticket_template(template_id, site_id[, user_email, summary])` — never substitute silently. On no or no match, fall through to rule 1 unchanged; if `ticket_templates` is absent from the catalog, skip silently. Verify the returned ticket id + agent/category via `get_ticket` — transport success proves nothing. Full mechanics: `grcitsm-ticketing.md` § Template-driven creation.
1. **Creates are identity-only; fields land in the follow-up update.** Ticket side: `create_new_ticket` → `update_ticket_fields` → `assign_agent` (add `set_ticket_client_site` second for cross-client — explicit `client_id` AND `site_id` — then re-point the requester at the site's designated General User via `update_ticket_fields({id, user_id})`, resolving the id via the `users` catalog). Asset side: `asset_types` → `create_asset` → `asset_type_fields` → `update_asset`. Detail: `grcitsm-ticketing.md`; chain doctrine: corpus `write-semantics.md` § 10.
2. **Run the pre-update lookup quintet before any ticket update** (`get_ticket`, `ticket_type_allowed_statuses`, `ticket_type_allowed_categories`, `ticket_type_fields`, `slas_and_priorities`) — `write-semantics.md` § 10.
3. **Route by ticket type.** CF writes on any type → `update_ticket_fields`; billable notes / `new_*` parent transitions → `agent_note`; structural changes → the dedicated `set_*`/`assign_agent` tools. Full routing table: `grcitsm-ticketing.md`.
4. **Every write is verified by a read.** Success strings and echoes prove nothing — `write-semantics.md` § 11.
5. **Payload cliff:** keep any long-form field ≤ ~200 chars per call; long content lands post-create, one field at a time — `write-semantics.md` § 8.
6. **Lookup values match verbatim** (zero-padded control IDs, no spaces after commas, live typos) — `write-semantics.md` § 3.
7. **Framework CFs: Controls before Requirements, always two calls**; asset-side adds the CFBaseline name-string rule and the new-type gotchas — `write-semantics.md` §§ 4-6.
8. **Bulk reads and writes stage to disk** — plan-to-file, approval gate, pilot; load `halo-bulk-update` for anything >20 rows.
9. **Roles:** the dual role model (GUID-keyed agent roles vs integer-keyed customer roles) is in corpus `data-model.md` § 6; the category rules + refresh SQL in `halo-agent-role-model.md`. Role GUIDs/int ids are tenant-specific — fetch live, never hardcode.
10. **Source priority:** `reference-docs/` (including the `halo-platform/` corpus) answers platform questions before any external documentation or web source; tenant-state questions are answered by live MCP reads, never the web. Full ladder: § Research Priority.

## Research Priority (Halo & GRCITSM questions)

Four tiers, in order. Never skip a tier silently.

1. **Vendored corpora first.** `reference-docs/halo-platform/` answers Halo API, data-model, SQL, and write semantics. Requirement text comes from the vendored compliance corpus where this marketplace ships one — reference-docs/fedramp-rules/fedramp-consolidated-rules.json (entry point), reference-docs/fedramp-2026-markdown/, reference-docs/cmmc/. Not every installation carries them; check before assuming absence. Never web-search what a corpus already answers, and never let an external source override it.
2. **Context7** for Halo product, feature, and how-to documentation. Two calls: `resolve-library-id`, then `query-docs`. Pass the user's full natural-language question verbatim — don't compress it to keywords. Curated library ids: `/websites/usehalo_halopsa_guides` (primary), `/websites/usehalo_haloitsm_guides` (secondary). Boundary: the corpus wins on write/read/SQL semantics; Context7 wins on product concepts and UI/admin guidance.
3. **Product documentation sites via WebFetch** when Context7 doesn't answer: `https://grcitsm.stratuscyber.com/` for GRCITSM-specific implementation questions (this platform's own documentation), `https://www.usehalo.com/guides/2338` for general Halo guides.
4. **Open web last** — `WebSearch`, or Exa search/fetch tools when the session has them. Never a silent fallback: name the tiers that came up empty and flag the answer as degraded coverage.

Tenant state is never a research question — answer it with live MCP reads (rule 10).

**Context7 availability.** Context7 is a connector, so it may be absent or logged out; a SessionStart availability check surfaces install and login guidance when it is. For best results, connect and authenticate it (Settings → Connectors, or `claude mcp add` with an API key). While it stays unavailable, fall through to the tier-3 documentation sites — do not drop straight to web search.
