diff --git a/plugin/commands/help.md b/plugin/commands/help.md index 850a825..e295fcb 100644 --- a/plugin/commands/help.md +++ b/plugin/commands/help.md @@ -13,6 +13,23 @@ Convoy — slash commands Orient yourself. Shows CONVOY_HOME, state DB, recent plans, recent run, whether the web viewer is up. Run this first if you're lost. +/convoy:onboard [path] + Run the onboard interview before the first plan. Captures platform + mandate, deployment style, approvers, compliance, and observability. + Onboard precedes everything — Convoy won't score platforms until it + knows how the team ships. + Examples: + /convoy:onboard + /convoy:onboard ./my-app + +/convoy:orient [path] + Read the repo's existing deployment signals and compare against saved + preferences. Surfaces drift (e.g. preferences say Fly but a vercel.json + appeared). Runs automatically before every plan once onboarded. + Examples: + /convoy:orient + /convoy:orient ./my-app + /convoy:ship [flags] Plan + apply end-to-end against a GitHub URL or local path. Real by default: opens a PR, rehearses locally, deploys to Fly. Pauses at each diff --git a/plugin/commands/onboard.md b/plugin/commands/onboard.md new file mode 100644 index 0000000..c2c0b61 --- /dev/null +++ b/plugin/commands/onboard.md @@ -0,0 +1,45 @@ +--- +description: Run the Convoy onboard interview for a repo — captures platform mandate, deployment style, approvers, compliance, and observability before the first plan. +argument-hint: [local-path] [--answers='{"platform":{"mandate":"fly"}}'] +--- + +You are running the Convoy onboard interview. Onboard **precedes everything** — Convoy does not plan, score, or author files until it knows how the team ships. + +## When to run this + +- The user is about to `/convoy:ship` a repo for the first time and you don't see a `.convoy/preferences.json` in the target. +- The user says "onboard this repo", "tell Convoy how we deploy", "set the platform", or similar. +- The plan page shows "No team preferences on file." +- `/convoy:ship` emitted "⚠ No team preferences on file." + +## What NOT to do + +Do not try to answer the interview questions yourself or pass `--answers` with fabricated values. The interview exists so the **operator** declares their patterns — Convoy's job is to hold that conversation, not to guess. + +The one exception: if the user has already stated their preferences in the chat (e.g. "we deploy to Fly, no compliance requirements, I approve PRs"), you may pass those as `--answers` to skip the interactive prompts. Confirm with the user before doing this. + +## Resolve the target path + +If `$ARGUMENTS` is empty, use the user's current working directory. Normalize relative paths to absolute based on the session cwd before passing to Convoy. + +## Run the interview + +```bash +cd "${CONVOY_HOME:-$HOME/convoy}" && npm run convoy -- onboard $ARGUMENTS +``` + +Keep this in the **foreground** — the interview is interactive, line-by-line. + +## After the interview + +Onboard writes `.convoy/preferences.json` in the target repo. Tell the user: + +> Preferences saved. Now run `/convoy:ship ` — Convoy will use your declared platform, approvers, and compliance settings for every plan going forward. + +If the user declared a platform mandate (e.g. "fly"), confirm: + +> Platform locked to **fly** for this repo. Override any time with `convoy onboard --platform=`. + +If they answered "not deployed anywhere" + "first deploy" (greenfield), Convoy will pick the platform itself on the next plan and write that pick as the mandate. Tell them: + +> Convoy will choose the platform based on your repo's signals and lock it in as your default. You can override it before applying if the choice doesn't fit. diff --git a/plugin/commands/orient.md b/plugin/commands/orient.md new file mode 100644 index 0000000..6a5fc2a --- /dev/null +++ b/plugin/commands/orient.md @@ -0,0 +1,50 @@ +--- +description: Orient Convoy to a repo's existing deployment setup — reads CI workflows, platform configs, secrets manager, observability stack, and compares against saved preferences to surface drift. +argument-hint: [local-path] [--json] +--- + +You are running `convoy orient` — Convoy's per-run drift detector. Orient reads what IS (repo artifacts) and compares it against what the team declared in `convoy onboard` (`.convoy/preferences.json`). It never modifies anything. + +## When to run this + +- Before planning a repo that's been active for a while: "what's in this repo's deploy setup?" +- After a team changes platforms without updating preferences: drift will surface here. +- Debugging a plan that picked the wrong platform: orient shows you what signals Convoy read. +- The user says "check what's deployed", "what does this repo use", "why did Convoy pick X". + +## What orient reads + +- `.github/workflows/*.yml` — deploy steps, trigger branches, `${{ secrets.* }}` references +- `fly.toml`, `vercel.json`, `railway.json`, `render.yaml`, `Procfile`, `docker-compose.yml`, `Caddyfile` +- `package.json` deps → secrets-manager packages (Doppler, Infisical, Vault, AWS SM) +- `package.json` deps → observability (Sentry, Datadog, New Relic, pino/winston) +- `.convoy/preferences.json` (if present) — compared against artifacts; drift is flagged + +## Resolve the target path + +If `$ARGUMENTS` is empty or `.`, use the user's current working directory. Normalize relative paths to absolute. + +## Run orient + +```bash +cd "${CONVOY_HOME:-$HOME/convoy}" && npm run convoy -- orient $ARGUMENTS +``` + +## Interpret the output for the user + +Structure a short response: + +**What Convoy found** +- Existing platform (if any): name, evidence file +- CI deploy target (if any): workflow name, deploy step +- Secrets manager (if any): tool name, source +- Observability (if any): tool(s) + +**Drift (if any)** +- Call out any mismatch between `preferences.json` and what orient found +- Include the exact remedy: `convoy onboard --platform=` to update preferences + +**Next step** +- If preferences exist and no drift: `/convoy:ship ` — ready to plan +- If preferences missing: `/convoy:onboard ` first +- If drift found: update preferences before planning or the declared platform will win over the artifact signal