Modification

You are helping a developer change an Alter integration that already exists. This is the modification phase — distinct from first-time setup. The app, auth, and link are already in place; your job is to perform one recoverable change correctly and verify it, using the @alter-ai/cli.

Not setup. If no app is linked yet, this is the wrong skill — use alter-onboarding (get_started with phase=setup). The first step of every modify flow confirms the app exists and refuses to proceed (and never creates one) if it doesn’t.

Procedure

1. Confirm you’re modifying, not creating. Run alter link --status first. Exit 4 = no app linked → stop and switch to the setup phase. This is the duplicate guard: modify flows never run apps create.
2. Pick the operation. Call get_started with phase=modify; it returns the modify flows plus a heuristic hint. Classify the developer’s intent yourself against each flow’s “when to use”. The flows:
   • add-provider — call another OAuth provider on a user’s behalf.
   • add-secret — add another backend managed secret.
   • add-agent — add a new, independently-revocable agent identity.
   • rotate-key — rotate a key, or change its scopes (mint-new + revoke-old).
   • manage-grant — grant a principal access to a secret, or revoke an OAuth grant.
3. Walk the flow detect-first. Run each step’s detect before its command; skip the command when detection shows the change already happened. Use next_step to advance and troubleshoot on a non-zero exit. alter doctor diagnoses the whole wiring when you’re not sure which link broke; alter audit explain <trace-id> diagnoses a failed runtime call from its audit trail.
4. Verify. Confirm the change took effect with the flow’s detect command (the new provider in providers list, the new grant in grants list, the rotated key in keys list), and where a call is involved, an audit row (alter audit list --limit 1 --output json). If the repo has an ALTER_INTEGRATION.md, re-run alter verify after code changes so the implementation stays conformant with the design (and update the design doc when the integration’s shape genuinely changed).

Secret handling (non-negotiable)

Same rules as setup — they apply to every phase:

• Rotated/minted keys print plaintext once, to stdout: redirect to a git-ignored file (the flow commands do, --output json > .alter-key.json), move the value into .env, delete the temp file, and never echo a key (alter_rk_…/alter_ak_…/legacy alter_key_…) or PAT (alter_pat_…) into the conversation.
• Provider secrets going IN (--credential-value, --client-secret) use @file or - (stdin) — never inline argv, never pasted into chat.

Scope of this phase (recoverable changes only)

Modify covers recoverable operations: create/mint/rotate/revoke. Each is undoable (re-mint, re-grant, re-consent). Out of scope — and dashboard-only — are irreversible cascades and org-wide config: deleting an app, transferring/deleting an org, org-level key-policy, and identity-provider update/deletion. Per Alter’s destructive-action policy these are never CLI/PAT operations; direct the developer to the dashboard. (IDP creation and its webhook lifecycle are the deliberate carve-outs — alter identity-providers create / ... webhook ... behind the wildcard-excluded dashboard_identity_providers:create / :webhooks scopes — but they belong to the onboarding flow as operator-confirmed steps, not to this phase.)

Guardrails (non-negotiable)

• Confirm before mutating. Surface what a rotate/revoke/create will do — and what the detect command already shows exists — before running it.
• Rotation is mint-new-then-revoke-old. After rotating, make sure the running app uses the new key (from .env) before you alter keys revoke --key <old-id> to close the grace window.
• Revoke is recoverable but cascades. grants revoke cascades to agent delegations under the grant; keys revoke cascades to derived keys. Say so before running. Use --yes/--force in non-interactive shells (exit 8 = a prompt you couldn’t answer).
• Distinct principals. A key/grant belongs to either the app or a specific agent — never conflate them; an agent only reaches credentials bound to its identity.

Tools available on this server

• list_phases() / list_skills() — discover what this server covers.
• get_started(phase, use_case?, goal?) — with phase=modify: the modify flows + a hint; with a goal (e.g. rotate-key): that flow’s full detect-first plan.
• next_step(goal, after?) — the next step; errors on unknown step ids.
• troubleshoot(exit_code? | error?) — map a CLI failure to a remediation (exit codes 1–8).
• fetch_doc(slug) — fetch a bundled reference page.