vercel__vercel-plugin/commands/_conventions.md

Command Conventions

Every slash command in this plugin follows a consistent structure so that the AI agent produces reliable, verifiable results. When authoring or updating a command file, include all of the sections below.

Required Sections

1. Preflight

Check prerequisites before doing any work:

• Project linked? — Verify .vercel/project.json exists. If not, guide the user through vercel link.
• CLI available? — Confirm vercel CLI is on PATH.
• Repo state — Note uncommitted changes, dirty working tree, or detached HEAD when relevant.
• Scope — Detect monorepo (e.g., turbo.json or pnpm-workspace.yaml) and confirm which package is targeted.

Preflight failures should produce clear, actionable guidance — never silently skip.

2. Plan

Before executing, state what will happen:

• List the commands or MCP calls that will run.
• Flag destructive or production-impacting operations and require explicit user confirmation.
• If multiple strategies exist (MCP-first vs CLI-fallback), state which path was chosen and why.

3. Commands

The operational core. Follow these conventions:

• MCP-first, CLI-fallback — Prefer the Vercel MCP server for reads; use CLI for writes or when MCP lacks coverage.
• Structured output — Request --format=json where available; parse and present results in a readable summary.
• No secrets in output — Never echo environment variable values. Show names and metadata only.
• Confirmation for destructive ops — Production deploys, env removal, cache purge, and domain changes require an explicit "yes" from the user.

4. Verification

After execution, confirm the outcome:

• Re-read state (e.g., vercel ls, vercel env ls) to confirm the operation took effect.
• Compare before/after where possible (e.g., deployment count, env var count).
• Surface errors or warnings from command output.

5. Summary

Present a concise result block:

## Result
- **Action**: what was done
- **Status**: success | partial | failed
- **Details**: key output (URL, counts, config changes)

6. Next Steps

Suggest logical follow-ups:

• After deploy → check logs, inspect build, verify preview URL.
• After env change → pull to local, redeploy if production.
• After status → fix any flagged issues, run deploy if stale.

File Naming

• Command files live in commands/ and end in .md.
• Files prefixed with _ (like this one) are meta-documents, not slash commands. They are excluded from plugin.json enumeration and not presented as user-invocable commands.

Frontmatter

Every command file must include YAML frontmatter with at least a description field:

---
description: One-line summary of what the command does.
---

Validation

scripts/validate.ts enforces these conventions. Every non-underscore command file is checked for the required sections: Preflight, Plan, Commands, Verification, Summary, Next Steps.