AGENTS.md · spotify/portal-ai-plugins

Sections

1. Repository structure
2. Design rules
3. Validation

First lines (shown under the repo's Apache-2.0 license)

# Spotify Portal AI Plugin

This repository packages Spotify Portal workflows for Claude Code, Codex, Cursor, and pi.

## Repository structure

- `skills/` contains the canonical Portal workflow instructions. Fleetshift workflows live there as `fleetshift-<workflow>` because hosts only discover skills one level deep (`skills/<name>/SKILL.md`), so they can't be grouped in a subfolder.
- `plugins/shunt/` contains the shunt plugin (Claude Code only for now): scripts, skills, hooks, and evals for routing I/O-heavy work to AiKA modes.
- `.claude-plugin/`, `.codex-plugin/`, and `.cursor-plugin/` contain host manifests; pi reads its manifest from the `pi` key in the root `package.json`.
- `assets/` contains shared Portal branding and product imagery.
- `.claude-plugin/marketplace.json` exposes the repository as a Claude Code marketplace.

## Design rules

- Keep the portal plugin at the repository root; additional plugins live under `plugins/<name>/` and are registered in `.claude-plugin/marketplace.json`. Move portal under `plugins/` only together with the other host manifests.
- Keep the plugin identifier `portal` so Claude Code skills use the `/portal:<workflow>` namespace.
- Keep `doctor` read-only.
- Keep each workflow canonical in `skills/`.
- Keep the root `package.json` `pi` key pointing only at the portal skills directory so `plugins/<name>` sub-plugins stay hidden from pi. Keep its metadata aligned with the other host manifests.
- Do not publish the bundled skills as standalone packages.
- Do not add release automation unless a tagged GitHub release or another distribution channel is explicitly planned.
- Preserve JSON output and dry-run safeguards when documenting Portal CLI operations.

## Validation

```bash
uv run --with pyyaml python \
  ~/.codex/skills/.system/plugin-creator/scripts/validate_plugin.py \
  .

claude plugin validate --strict .

# shunt hook + transport evals (no Portal access needed)
bash plugins/shunt/evals/run.sh
```