csa-skilljar: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code (claude.ai/code) when working in this repository.

What this repository is

csa-skilljar — a Python library (import name csa_skilljar) and local stdio MCP server over both Skilljar REST APIs. It reproduces the official Skilljar MCP server's 73-tool surface exactly, then adds the capabilities that exist only in v1.

Status: shipped and in use. All seventeen roadmap blocks are on main — 112 tools (84 over v2, 27 over v1, plus demonstration_plan) across 37 modules in src/, with 62 test files. Released to PyPI through v0.15.0; installed on staff machines by DesktopSetup.

Still true, and the thing to keep honest: no write has ever run against real Skilljar. Every read is exercised against the production organization; the write half has only ever run against FakeBackend. That is what v1.0.0 waits on — see WAITING-FOR-003. Do not describe writes as verified.

Where things live

• docs/superpowers/specs/2026-08-26-csa-skilljar-design.md — the authoritative design. Read it before proposing anything. Architecture, routing rule, credential model, error taxonomy, phasing, and three appendices of probe-verified facts.
• specs/ — upstream OpenAPI snapshots, fetched 2026-08-26. skilljar-v1-openapi.yml (3.0.3, 160 paths / 340 ops) and skilljar-v2-openapi.json (3.1.0, 44 paths / 82 ops). These are snapshots of someone else's moving target — see "Upstream drift" below. specs/PROVENANCE.md records where each file came from, its sha256 and byte count, and the last document-level diff against live. Already drifted: live v2 had 48 paths on 2026-09-16 (46 on 2026-08-31). /v2/assets/ and /v2/assets/{id} were the first time the ADR-002 retirement trigger fired; /v2/students/{id}/relationships/ domain-memberships/ followed, and the response media type is now application/vnd.api+json throughout. v1 has not drifted at all. See TODO.md.
• analysis/ — the 66-entity reconciliation of both APIs (entity-inventory.csv/.json), the live OAuth scope catalogue, and a browsable surface map.
• docs-html/ — the rendered vendor doc pages, kept for provenance. Low value; the specs are the useful artifact.
• GOALS.md / BUSINESS-CASE.md — what success is, and the honest argument that this project should get smaller over time. Read before proposing scope changes.
• TODO.md — the index of ALL open work, per the CINO todo-index convention. Sweeping this plus open GitHub Issues finds everything. It also carries a consideration pile of things deliberately not committed to — check it before proposing a "missing" feature.
• DECISIONS-ADR.md + DECISIONS-ADR/ — seven technical decisions with their rejected alternatives. ADR-002 (routing) and ADR-004 (no version in tool names) are load-bearing; do not contradict them without a superseding ADR.
• DECISIONS-PRD.md + DECISIONS-PRD/ — scope, audience, and explicit out-of-scope.
• SECURITY-RESOURCES.md — exposure surface and the prompt-injection threat. Constrains any change that surfaces course content to a model.
• DATA-RESOURCES.md / DATA-NEEDS.md — what data is handled and what is deliberately never stored. No caching, no persistence — proposing either changes the security posture and needs its own ADR.
• WAITING-FOR.md + WAITING-FOR/ — external conditions with observable triggers. 001 is the retirement trigger for each v1 family; 002 blocks all of Phase 1.
• FRICTION.md + FRICTION/ — friction log. Low bar: if it is an annoyance for a human or an AI, log it.
• OPERATIONAL-RESOURCES.md — the one recurring job (check_upstream.py). Check its "Next review" date against today when working here.
• RACI.md — authority by domain. Note: credential issuance is never delegated to AI.
• CHATGPT.md / GEMINI.md — pointers to this file, deliberately not copies.