# Setup

One-time setup after installing the `grcitsm-analyst` plugin.

## 1. Prerequisite: a GRCITSM tenant with the MCP tool catalog

Your GRCITSM tenant must expose the **GRCITSM MCP tool catalog** — the set of tools (ticket operations, asset operations, control lookups, SSP reconciliation reports) the plugin's skills and agents call. Stratus Cyber provisions this catalog as part of your tenant delivery. If you're unsure whether your tenant has it, run `/grcitsm-analyst:setup` after step 2 — it reports exactly what's missing.

## 2. Connect your tenant: the claude.ai OAuth connector

The plugin reaches your tenant through your organization's claude.ai OAuth connector — added once by an organization owner, then available to members everywhere they use Claude (chat, Cowork, and Claude Code).

1. An organization owner adds your tenant's MCP endpoint as a custom connector under **Settings → Connectors** in claude.ai (endpoint URL supplied by your Stratus Cyber engagement team).
2. **Name the connector starting with `GRCITSM`** — e.g. `GRCITSM`, `GRCITSM Dev`, `GRCITSM Halo Gov`. The plugin discovers the connection by that name prefix; a connector named anything else is not picked up. Tools then appear in Claude Code as `mcp__claude_ai_GRCITSM__CF_*`.
3. Each member completes the OAuth sign-in against your tenant the first time they use the connector.

If the connector shows as registered but not connected in a Claude Code session, run `/mcp`, select the GRCITSM server, and authenticate.

## 2.5 Recommended permissions (reads free, writes prompt)

Your tenant is a live system of record, so the safe posture is: **let reads run freely, prompt on every write.** Without an explicit rule, Claude Code's auto-mode classifier guesses per call — and that guess is name-sensitive (a server named `…uat` may read as a harmless test box and auto-pass writes, while a production-sounding name gets writes denied). Pin it explicitly so behavior doesn't depend on the name:

```json
{
  "permissions": {
    "allow": ["mcp__claude_ai_GRCITSM__*"],
    "ask": [
      "mcp__claude_ai_GRCITSM__CF_create_new_ticket",
      "mcp__claude_ai_GRCITSM__CF_update_ticket_fields",
      "mcp__claude_ai_GRCITSM__CF_agent_note",
      "mcp__claude_ai_GRCITSM__CF_assign_agent",
      "mcp__claude_ai_GRCITSM__CF_set_ticket_parent",
      "mcp__claude_ai_GRCITSM__CF_set_ticket_assets",
      "mcp__claude_ai_GRCITSM__CF_set_ticket_client_site",
      "mcp__claude_ai_GRCITSM__CF_set_ticket_sla_and_priority",
      "mcp__claude_ai_GRCITSM__CF_create_asset",
      "mcp__claude_ai_GRCITSM__CF_update_asset",
      "mcp__claude_ai_GRCITSM__CF_set_asset_relationships",
      "mcp__claude_ai_GRCITSM__CF_update_system_information",
      "mcp__claude_ai_GRCITSM__CF_create_kb_article",
      "mcp__claude_ai_GRCITSM__CF_update_kb_article",
      "mcp__claude_ai_GRCITSM__CF_update_component_from_library",
      "mcp__claude_ai_GRCITSM__CF_create_ksi_data_requests",
      "mcp__claude_ai_GRCITSM__CF_create_ksi_validations",
      "mcp__claude_ai_GRCITSM__CF_reconcile_ssp_assets",
      "mcp__claude_ai_GRCITSM__CF_reconcile_ssp_relationships_ci_ir",
      "mcp__claude_ai_GRCITSM__CF_reconcile_ssp_relationships_ir_is"
    ]
  }
}
```

`allow` covers the ~45 read tools (no prompts); the ~20 write tools sit in `ask`, which forces a y/n prompt on every mutation (`ask` takes precedence over `allow`). Add it via `/permissions` or by editing your settings file — Claude can't add it for you (an agent can't widen its own permissions).

> **The rule must match your server name exactly, and it's case-sensitive.** These rules assume a claude.ai connector named exactly `GRCITSM`, which Claude Code exposes as `mcp__claude_ai_GRCITSM__…`. If your connector name carries a suffix (e.g. `GRCITSM Dev` → `mcp__claude_ai_GRCITSM_Dev__…`), use that in the `mcp__<name>__…` prefix — run `/mcp` to see the exact server name. A mismatch silently leaves writes ungated/blocked by the classifier instead. If you rename the connector later, update these rules to match.

## 3. Run setup

```
/grcitsm-analyst:setup
```

This one command does the rest of setup for you:

- **Verifies** the GRCITSM connection is available and every required tool is present (reports exactly what's missing if not).
- **Scaffolds** the working directories the pipelines use:

  ```
  your-project/
  ├── inputs/     # documents to ingest: policies, procedures, transcripts, prior SSPs
  └── outputs/    # generated SSPs, change plans, reports, and per-run state (outputs/<run>/state/)
  ```

- **Installs** the bulk-write workflow into `.claude/workflows/halo-apply.js` (see next section).

Once it reports **Ready**, try `/grcitsm-analyst:ssp-generate` for a read-only preview of your current SSP state.

> **Re-run `/grcitsm-analyst:setup` after every plugin update.** It compares the shipped `halo-apply.js` against your project's copy and refreshes it if the plugin shipped a newer version — so you don't have to track workflow changes in the CHANGELOG by hand.

## 4. About the bulk-write workflow (optional — only for large writes)

`/grcitsm-analyst:setup` installs `halo-apply.js` for you, but here's what it's for: you do NOT need it for reads, lookups, SSP generation, or small writes (single tickets/assets, a handful of rows). It matters only for large bulk writes (the writer phase of `/grcitsm-analyst:ssp-ingest` / `ssp-interview`, reconciliations, multi-row updates), where a deterministic workflow drives the apply loop.

**Manual path** (if you ever need to copy it without running setup) — Claude Code loads workflows only from your project's `.claude/workflows/` directory:

```bash
mkdir -p .claude/workflows
cp "$(ls -d ~/.claude/plugins/cache/stratus-grcitsm-marketplace/grcitsm-analyst/*/ | sort -V | tail -1)workflows/halo-apply.js" .claude/workflows/
```

**Without the workflow:** bulk writes still work — the pipeline falls back to a main-thread apply loop driven by `pipeline.py`. You lose deterministic round-driving (it matters at 40+ actions), not the capability.

## 5. FedRAMP / CMMC reference docs

The `fedramp-expert` and `cmmc-expert` advisors answer requirement questions from a bundled reference corpus under `plugins/grcitsm-analyst/reference-docs/`:

| Corpus | Form | Always present? |
|---|---|---|
| CMMC reference (`cmmc/`) — practice XML, L2/L3 assessment + scoping guides, FAQs | vendored (committed) | Yes |
| FedRAMP Rev5 baselines (`fedramp-rev5/`) — Low / Moderate / High parameter CSVs | vendored (committed) | Yes |
| FedRAMP Consolidated Rules (`fedramp-rules/`) — `fedramp-consolidated-rules.json` | vendored (committed) from [FedRAMP/rules](https://github.com/FedRAMP/rules) | Yes |
| FedRAMP 2026 narrative corpus (`fedramp-2026-markdown/`) | vendored (committed) from [FedRAMP/2026-markdown](https://github.com/FedRAMP/2026-markdown) | Yes |
| FedRAMP Machine Readable submission schemas (`fedramp-schemas/`) | vendored (committed) from [FedRAMP/schemas](https://github.com/FedRAMP/schemas) | Yes |

Every corpus works out of the box — the FedRAMP corpora are vendored as plain tracked files, not git submodules, so no `git submodule update` step is needed. Each vendored FedRAMP directory carries a `VENDORED.md` recording the upstream repository and commit it was copied from. Do not hand-edit vendored files; local edits are overwritten on the next refresh.

To refresh the FedRAMP corpora to the latest coherent upstream snapshot, run the included helper from the repo root (a weekly GitHub Actions workflow also opens a refresh PR automatically when upstream changes):

```bash
./scripts/update-fedramp-refs.sh          # re-vendor latest upstream
./scripts/update-fedramp-refs.sh --check  # report vendored-vs-upstream SHAs only
```
