spotify/portal-ai-plugins

```bash
${CLAUDE_PLUGIN_ROOT}/scripts/bulk-read --question "<question>" --paths <file1> [<file2> ...]
```

Each call is independent. To ask a follow-up, ask again with the same `--paths` — the files
go to AiKA, never into your context, so re-sending them costs you nothing.

Verify specific line numbers or exact values before using them in edits.

```bash
# Generate and write directly to target file
${CLAUDE_PLUGIN_ROOT}/scripts/code-write --spec "<what to generate>" --reference <reference-file> --target <output-path>

# Output to stdout instead (omit --target)
${CLAUDE_PLUGIN_ROOT}/scripts/code-write --spec "<what to generate>" --reference <reference-file>
```

Each call is independent. To build on what was just generated, pass that file as the
`--reference` for the next call.

Review the output and make surgical edits for the ~5-20% that needs Claude-level judgment.

# Use Portal Actions

Use the CLI whenever the action ID is known directly or can be found through one action listing.

## Discover and inspect

```bash
npx @spotify/portal-cli actions list --json
npx @spotify/portal-cli actions <action-id> --help
```

Prefer a dedicated CLI workflow such as `search`, `owner`, or `service` when it already matches the user's goal.

## Invoke safely

# Diagnose Spotify Portal

Run a read-only health check for the current coding-agent host. Do not install,
authenticate, select an instance, or invoke a mutating Portal action.

## Diagnostic workflow

### 1. Inspect the host plugin

Use only the command for the current host:

```bash
claude plugin list --json
codex plugin list --available --json

# Send Portal CLI Feedback

Submit the user's feedback about the Portal CLI through the feedback action:

```bash
npx @spotify/portal-cli actions telemetry:submit-feedback --text "<feedback>" --source cli --json
```

## When to offer

- The user explicitly asks to send feedback about the Portal CLI.
- The user voices a clear impression, complaint, suggestion, or praise about the Portal CLI or one of these workflows during a session. Offer once; do not nag.

Scope is the CLI experience: commands, flags, output, auth flow, and these plugin workflows. Do not submit feedback about the Portal product UI, bug reports that need a response, support requests, or feedback about other tools.

# Check a Fleetshift shift

This skill is **read-only and idempotent**. It never mutates anything and
needs no confirmation, so it is safe to run anytime — including days or weeks
after a shift was created or run. The `npx @spotify/portal-cli actions
fleetshift:<action>` calls below never change state.

Use it to answer:

- What shifts exist and how they are progressing overall.
- Which targets of a shift finished, failed, are still queued, or are running.
- Whether PRs were opened for a shift and their current state (open/merged/
  closed).

# Create PRs from a Fleetshift shift

Once Fleetshift has finished running a shift on a set of targets (the agent
job completed successfully), you can open one pull request per completed
target. Only targets whose job is complete are eligible for a PR.

> **Mutating action — explicit confirmation required.** Do **not** call
> `fleetshift:create-prs` until the user has explicitly confirmed how many PRs
> will be opened and for which targets. Ask for a clear "yes" first.

## Prerequisites

- The Portal CLI is authenticated: `npx @spotify/portal-cli auth show`.
  If it isn't, ask the user to run `npx @spotify/portal-cli auth login`.

# Create a Fleetshift shift

A Fleetshift **shift** is a reusable definition: an agent prompt plus a set of
repository targets and PR metadata. Once created, a shift can be run
(`fleetshift-run-shift`), checked on (`fleetshift-check-shift`), and have PRs opened from it
(`fleetshift-create-prs`).

This skill creates **agent**-type shifts only: the shift runs an LLM agent
against each target repository with a prompt you provide.

> **Mutating action — explicit confirmation required.** Do **not** call
> `fleetshift:create-shift` until the user has explicitly confirmed the shift
> name, the agent prompt, the target scope, and the PR metadata. A "looks
> good"/"go ahead" is not enough — ask and get a clear "yes" first.

# Run a Fleetshift shift

Running a shift triggers an agent job per target repository, then monitors
each triggered job until it finishes (or until a bounded wait expires).

> **Mutating action — explicit confirmation required.** Do **not** call
> `fleetshift:trigger-shift` until the user has explicitly confirmed which
> shift and which targets to run. Ask for a clear "yes" first.

## Kill switch: stop a shift

If the user says stop, cancel, abort, "wait", "never mind", or otherwise
changes their mind at **any** point, do this right away. Stopping doesn't
need the confirmation step that triggering does:

# Troubleshoot a Fleetshift shift

This skill is **read-only**. It only inspects shift, target, job, and log
state to explain _why_ something failed — it never mutates, triggers, or
re-opens anything, and needs no confirmation. If a fix is needed, it hands off
to the mutating skills (`fleetshift-run-shift`, `fleetshift-create-prs`), which enforce their own
explicit confirmation.

Use this for:

- A target whose status is `jobFailed`, `stopped`, or `skipped`.
- A shift where the status breakdown shows failures.
- A soundcheck check that is still failing after a shift ran.

# Search Spotify Portal

Use the Portal CLI search command as the source of truth:

```bash
npx @spotify/portal-cli search --help
npx @spotify/portal-cli search <query> --limit 10 --json
```

## Search workflow

1. Use the user's wording as the initial query.
2. Restrict the search with `--type software-catalog` or `--type techdocs` only when the request clearly targets one source.
3. Return a shortlist rather than the raw result document.

# Inspect a Portal Service

Use the Portal CLI as the source of truth. Prefer JSON output when composing an answer.

## Resolve the service

Run help before relying on command flags:

```bash
npx @spotify/portal-cli owner --help
```

For a service name:

# Set Up Spotify Portal

Set up the Portal CLI for every supported host.

## Critical rules

1. Never ask the user to paste access tokens, authorization codes, or other credentials into chat.
2. Run `--help` before relying on a Portal CLI or host command or flag.
3. Prefer `--json` whenever the agent consumes command output.
4. Never assume the default authenticated Portal instance when more than one instance is listed. Ask the user which instance to use.

## CLI invocation

Verify Node.js and npm: