# grcitsm-analyst

Claude Code plugin for operating a GRCITSM (Halo PSA) tenant configured with the GRCITSM MCP tool catalog: ticket and asset workflows, project & budget operations, SSP authoring and generation, compliance lookups, and safe bulk-write operations.

Where this README says "SSP", the underlying structure is really an OSCAL-aligned spine of Halo assets — Capability, Component, Control Implementation, Implemented Requirement, Implementation Statement, and Set Parameter (Capability is a Halo-native rollup layer; the other five map directly to OSCAL SSP elements). That one spine is the source of truth used to render the traditional System Security Plan (SSP) and, going forward, the FedRAMP Security Decision Record (SDR), which replaces the traditional SSP under the FedRAMP 2026 rules.

## Architecture

The plugin has three layers over the `grcitsm` MCP tool catalog:

- **Skills** — workflow doctrine (ordering, routing, write discipline the tool descriptions can't carry), auto-loaded when relevant.
- **Agents** — delegated work: an SSP team, a bulk-write team, and operational agents that compose the catalog. The foundation owns all Halo writes; upper-layer plugins compose action files.
- **Workflow** — `workflows/halo-apply.js`: the deterministic apply-loop driver for the bulk-write pipeline (executor waves in dependency order, dead-lease reclaim, ledger-based resume). Shipped frozen and auto-surfaced as the invocable `grcitsm-analyst:halo-apply` — never copied into your project, so it never drifts. Optional; only used for large bulk writes.

**Reference docs** — `reference-docs/`: the vendored `halo-platform/` corpus (shared platform doctrine — write semantics, API/MCP semantics, data model, SQL dialect, SSP narrative doctrine; byte-identical across plugins, synced not hand-edited), GRCITSM ticketing doctrine + tenant catalog, per-domain deep-dive docs offloaded from the skills (SSP write surfaces, ingest phases, asset schemas, bulk/pipeline operations), required MCP tool manifest, SSP spine reconciliation patterns, run-state conventions. These reference docs (including the `halo-platform/` corpus) are consulted before any external documentation or web source for platform questions; tenant state always comes from live MCP reads.

## Commands (7)

| Command | Description |
|---|---|
| `/grcitsm-analyst:setup` | Verify the `grcitsm` MCP server + tool catalog, scaffold working directories, and install/update the bulk-write workflow |
| `/grcitsm-analyst:ssp-generate` | Render one markdown SSP per Class baseline + cross-baseline gaps report from current Halo state (read-only) |
| `/grcitsm-analyst:ssp-ingest` | Ingest documentation from `inputs/` into the Halo SSP asset spine via the six-phase CHANGE-PLAN pipeline |
| `/grcitsm-analyst:ssp-interview` | Interview-driven SSP authoring — greenfield gathering by conversation, shared downstream phases with ssp-ingest |
| `/grcitsm-analyst:ssp-compile` | Compile flat SSP CSV manifests + companion narratives into a halo-action-pipeline `actions.jsonl` (library-first, changed-only/drift), or project any action file to a review CSV |
| `/grcitsm-analyst:halo-apply` | Apply a composed `actions-*.jsonl` file to Halo via the executor fleet (leases, heartbeats, reclaim) |
| `/grcitsm-analyst:demo-build` | Build or rebuild the stored demo system into a tenant — regenerate lookups, compile the scaffold, apply each step file, verify against the tenant |

## Agents (12)

| Agent | Purpose |
|---|---|
| `grcitsm-analyst-coordinator` | Routes ad-hoc SSP / Halo / project-budget questions to the right specialist; enforces the MANDATORY SSP Review and Technical-Accuracy Chains |
| `ssp-author` | Read-only SSP rendering from current tenant state (drives `/ssp-generate`) |
| `ssp-curator` | Classify / extract / reconcile documents into a draft CHANGE-PLAN |
| `ssp-interviewer` | Conversational greenfield SSP gathering |
| `ssp-reviewer` | CHANGE-PLAN quality gate (technical accuracy + editorial polish) |
| `grcitsm-tech-reviewer` | Report-only accuracy gate on FedRAMP / CMMC answers (bare lookups included) and pre-production Halo output (runbook JSON, SQL, action plans) |
| `ssp-writer` | Composes the residual approved CHANGE-PLAN rows into action files for `/grcitsm-analyst:halo-apply` (never writes directly) |
| `halo-pipeline-coordinator` | Main-thread role spec that routes phases and drives the bulk apply loop |
| `halo-action-planner` | Composes an immutable action file for the bulk-write pipeline |
| `halo-action-executor` | Applies one action per call against the tenant, resumable |
| `halo-ops-agent` | Non-billable, ≤5-row operational ticket field updates (priority, dates, custom fields) |
| `halo-project-manager` | Project (type 5) / Project Task (type 20) setup, read-merge-write budgets, task→budget attribution, and budget-vs-actual burn-down reporting |

## Skills (18)

| Skill | Purpose |
|---|---|
| `demo-build` | The stored demo system as flat CSV plus its compiler — replay Cloud Assets, library Components/Implementation Statements, and the operational ticket set into any tenant |
| `demo-smoke-test` | End-to-end smoke test of the full MCP + SSP pipeline, run as a demo rebuild in its own canonical 17-step sequence — tool-coverage matrix, continuous findings ledger, human approval walk-through (internal; not in the client marketplace) |
| `grcitsm` | Router and workflow primer: create → update chains, ticket-type → tool routing, pre-update lookups, and where every piece of platform/tenant doctrine lives |
| `ssp-csv-compile` | Compile flat CSV structure manifests + companion narrative markdown into a halo-action-pipeline `actions.jsonl` (library-first resolution, three-phase framework CFs, changed-only/drift emit, fail-loud validation); reverse-project any action file to plan-review.csv |
| `halo-action-pipeline` | The generic plan→apply pipeline for any multi-row Halo write |
| `halo-asset-import-spreadsheet` | Spreadsheet-driven bulk asset writes: user-reviewable .xlsx/.csv plan applied via the MCP pipeline; documents the native importer's measured limits |
| `halo-bulk-update` | Six-phase methodology for bulk operations touching >20 rows |
| `halo-project-management` | Project/task/budget operations: setup, SOW-informed structure, the read-merge-write recipe for the full-replace `budgets[]` array, budget-type attribution, budget-vs-actual tracking |
| `halo-ssp-asset-model` | Dictionary of the SSP asset spine (per-type schemas, OSCAL mappings, relationship allow-list) |
| `halo-ssp-asset-write-conventions` | Disciplined-write rules for the SSP asset spine |
| `ssp` | SSP asset spine workflow primer (Capability → Component → CI → IR → IS → SP) |
| `ssp-brand-voice` | Narrative voice rules for SSP prose |
| `ssp-capability-seed-list` | The canonical Capability taxonomy |
| `ssp-generate` | Render a markdown SSP from current Halo state |
| `ssp-ingest` | Ingest documentation artifacts into the SSP asset spine |
| `ssp-interview` | Interview-driven greenfield SSP authoring |
| `ssp-review-standards` | Reviewer discipline for the SSP write pipeline |
| `system-package` | The unified system package: one on-disk format for demo data, document ingest, interview capture, and tenant capture, with one driver (validate/check/compile/diff/render/approve) fronting the family compilers |

## Setup

See [SETUP.md](../../SETUP.md) at the marketplace root. Short version: add your tenant's MCP endpoint as a claude.ai OAuth connector named starting with `GRCITSM`, then run `/grcitsm-analyst:setup` — it scaffolds `inputs/`/`outputs/` and installs the workflow for you.

## Safety model

All bulk writes flow through the CHANGE-PLAN approval gate: the plugin composes a reviewable plan first, and nothing is written to your tenant until you explicitly approve. Single-row writes follow per-row verification (read-back via `get_asset`/`get_ticket`). Halo's native asset change history records every field-level write for audit.

## License

The plugin's code, prompts, and documentation are licensed under the Apache License 2.0 (see the LICENSE file at the marketplace root, with attribution in NOTICE). The vendored government reference corpora distributed with the client marketplace (the FedRAMP consolidated rules, FedRAMP 2026 narrative, Rev5 baselines, FedRAMP machine-readable schemas, and the CMMC practice set) are works of the US Government redistributed unmodified; they retain their own status and are not covered by the Apache-2.0 grant.
