# Hydra Onboarding Spec **Version:** 1.0 | 2026-05-01 **Status:** DRAFT — pending brand identity from Neil before visual implementation --- ## Design Principles 1. **Value before completion.** The user sees a real finding on their real code before the onboarding screen closes. 2. **Aha moment = first fix merged.** Every screen before that moment exists to remove friction toward it. 3. **One action per screen.** No configuration menus. No sidebars. One clear thing to do. 4. **Demo repo as fallback.** If their repo returns no findings, we switch to a pre-loaded demo repo transparently. They never hit a dead end. 5. **Plan selection at peak motivation.** The user sees their first finding before they choose a plan. They already know it works when the pricing question arrives. 6. **Free is real.** No degraded experience. No "upgrade to see your results." Free gets the full product. The limits are generous enough to make it real. --- ## Flow Overview ``` GitHub Marketplace | v [1] Install GitHub App (GitHub native flow) | v [2] Enter Anthropic API key | v [3] Pick a repo | v [4] Discovery + Audit running (live progress) | v [findings ready] | [5] First finding surfaced | v [6] Plan selection — Free / Team trial / Business trial | v [user picks a plan] | [7] Fix runs (live progress) | v [8] PR created — "Hydra opened a PR. Review and merge it." | v [PR merged — aha moment complete] | [9] Dashboard — onboarding complete ``` --- ## Screen-by-Screen Spec ### Step 1: Install GitHub App (GitHub native) This is GitHub's standard App install flow. Hydra does not control it. When the install completes, GitHub redirects back to Hydra with `?installation_id=...&code=...`. **Handled by:** existing `SetupWizard.tsx` callback. **Edge case:** user installs on a personal account vs. an org. Both work. No special handling needed. --- ### Step 2: Enter Anthropic API Key **Screen headline:** Connect your Anthropic API key **Body copy:** Hydra uses your own Anthropic account. You control the costs. We never mark them up. [API key input field — masked] [Where to find your key] (link to Anthropic console) [Continue →] **Validation:** - Test the key against the Anthropic API before accepting. Show inline error if invalid. - Do not advance until the key validates. **Tone:** matter-of-fact. This is a technical user. No hand-holding. --- ### Step 3: Pick a Repo **Screen headline:** Which repo do you want to start with? **Body copy:** Hydra will run a full Discovery and Audit. Pick the repo where you want to see it work first. [GitHub repo picker — native GitHub org/repo selector, populated from the App installation scope] **Notes:** - Free-pick. No Hydra-imposed filtering or recommendation. Standard GitHub repo selector. - Show repo name, last pushed date. That is enough signal for the user to pick. - If the installation has no repos in scope, prompt them to go back to GitHub and expand access. [Start →] --- ### Step 4: Discovery + Audit Running **Screen headline:** Hydra is reading your codebase This is the most important screen in the onboarding. It cannot be a spinner. The user needs to see that something real is happening. **Live progress feed (sequential, not parallel display):** ``` Reading your codebase... Mapping your architecture... Identifying languages and frameworks... Running 39 audit tools... Verifying findings against your code... Reviewing results... ``` Each line appears as the underlying step completes. If a step takes more than 3 seconds, show an animated ellipsis. **Cost/time estimate visible on screen:** "Typical audit: 8-12 minutes, $15-35 in Anthropic costs." **What happens if their repo produces zero findings:** Silently switch to the Hydra demo repo. Do not tell the user their repo was clean yet. Show findings from the demo repo. After onboarding completes, surface a banner: "Your repo is in great shape — no findings detected. Here's what Hydra found in a demo repo to show you how it works. [Run Hydra on another repo]." **Back button:** disabled during this step. They cannot interrupt a running audit. --- ### Step 5: First Finding Surfaced **Screen headline:** Hydra found [N] issues in [repo name] Surface the top finding. Not a list. One finding, shown clearly. **Finding card includes:** - Severity badge (Critical / High / Medium) - Title (e.g., "SQL query constructed from unvalidated user input") - File path + line number - Two-sentence plain-English explanation of the risk - Code snippet showing the affected lines Below the finding card: *"Hydra can fix this automatically — write the code change, run your tests, and open a PR."* **Do not show the full findings list here.** The goal is to make one finding feel concrete and solvable, not to overwhelm. [See the fix →] --- ### Step 6: Plan Selection This screen appears after the user has seen their first real finding. They already know the product works. This is the right moment to ask them to choose. **Screen headline:** Choose how you want to run Hydra **Subhead:** You just saw what it can do. Now pick your plan. --- **Free** No credit card. Full Discovery and Audit. 5 fixes per month. 5 Linear cycles per month. 1 doc run per month. Unlimited repos. [Continue on Free] --- **Team — $20/dev/month** 14-day free trial. No credit card today. Unlimited fixes. Unlimited doc runs. Up to 5 repos. Custom agent rules. [Start Team trial] --- **Business — $40/dev/month** 14-day free trial. No credit card today. Unlimited repos. Jira integration. Audit logs + usage reporting. Priority fix queue. [Start Business trial] --- **Enterprise** SSO. SAML. RBAC. VPC. Compliance. SLAs. [Talk to us] --- **Notes on plan selection:** - Free: no Stripe record created. Zero friction. - Team and Business trials: 14-day trial, no credit card required at signup. Stripe record created on day 14 if not cancelled. User gets a reminder email at day 10. - Trial selection does not interrupt the onboarding. After picking a plan, the fix runs immediately. - Enterprise routes to a contact form or Calendly link. Does not continue through the onboarding fix flow (enterprise users get a white-glove path). --- ### Step 7: Fix Running **Screen headline:** Hydra is fixing it **Live progress feed:** ``` Creating isolated workspace... Running your test suite to establish a baseline... Writing the code change... Running tests again to verify nothing broke... Running lint and format checks... Reviewing the diff... Opening a pull request... ``` Same pattern as Step 4. Real progress, not a spinner. **Estimated time:** "Fix typically takes 3-6 minutes." --- ### Step 8: PR Created **Screen headline:** Pull request ready for review **Body:** Hydra opened a PR in [repo name]. Review it and merge when you're ready. [View PR on GitHub →] Below: a brief summary of what the fix did. Two to three sentences max. *"When your team merges the PR, Hydra automatically closes the finding and logs it as resolved."* [Go to dashboard →] (secondary CTA — they can skip the PR review step) --- ### Step 9: Dashboard — Onboarding Complete The user lands on the full Hydra dashboard. Onboarding is complete. **First-time dashboard state:** - One finding card visible (the one from onboarding) - Sidebar checklist (persistent, dismissible after all items complete): - [x] Connected GitHub - [x] Connected Anthropic API key - [x] First audit complete - [x] First fix opened - [ ] First fix merged - [ ] Run Hydra on a second repo The checklist disappears once all items are checked or the user explicitly dismisses it. --- ## Demo Repo Spec **Trigger:** audit of user's selected repo returns zero findings. **Demo repo requirements:** - A real-looking Python or TypeScript codebase (not "hello world") - 3-5 pre-seeded findings across Critical, High, and Medium severity - At least one finding that is fixable via Hydra's fix workflow within the onboarding time budget - Hosted in the Hydra GitHub org, read-only to users - Pre-audited so results load instantly (no LLM cost for the demo path) **User experience during demo fallback:** - No interruption. The progress feed continues as normal. - After Step 8, banner appears: "Your repo is in great shape — no findings were detected. The finding above is from a demo repo. [Run Hydra on another repo]" **What the user must NOT see:** - An error state - An empty screen - An explanation of why they're seeing a demo repo BEFORE they've experienced the fix flow --- ## Edge Cases | Scenario | Handling | |---|---| | GitHub OAuth fails | Error with retry. Contact support link. | | Anthropic API key invalid | Inline error. "Check that your key starts with sk-ant-". Do not advance. | | Audit times out (>15 min) | Surface partial findings if any exist. If none, switch to demo repo. | | Fix fails all gauntlet gates | Show the finding, explain the fix could not be completed automatically. Offer to create a Linear ticket instead. Do not dead-end. | | User closes the browser mid-onboarding | Resume from the last completed step on next login. State is persisted server-side. | | User installs on a repo with no supported languages | Explain supported languages, prompt to pick a different repo. Do not switch to demo repo silently — this requires explicit re-selection. | | Enterprise user clicks "Talk to us" | Route to contact form. Separate path. Onboarding ends here for them. | --- ## Activation Metrics These are the events to instrument from day one. | Event | What it measures | |---|---| | `onboarding_started` | GitHub App install callback received | | `api_key_connected` | Anthropic key validated and saved | | `repo_selected` | User picked a repo and clicked Start | | `audit_completed` | Findings returned (real or demo) | | `finding_viewed` | Step 5 rendered | | `plan_selected` | Which plan (free / team-trial / business-trial / enterprise) | | `fix_started` | Fix workflow kicked off | | `pr_created` | PR opened on GitHub | | `pr_merged` | Aha moment. Webhook from GitHub on merge. | | `onboarding_completed` | User reached dashboard | | `demo_repo_fallback` | Audit returned zero findings, demo used | **Target benchmarks:** - `api_key_connected` → `audit_completed`: under 12 minutes - `finding_viewed` → `plan_selected`: under 2 minutes (low-friction decision) - `plan_selected` → `pr_created`: under 8 minutes - `pr_merged` within 24 hours of install: activation success --- ## Open Items | Item | Owner | Notes | |---|---|---| | Trial terms (14-day, no CC) | Tristan | Confirm before Stripe implementation | | Demo repo contents | Tyler | Need 3-5 high-quality pre-seeded findings across severity levels | | Resume-from-last-step implementation | Tyler | Server-side state persistence required | | Contact form / Calendly for Enterprise | Tristan | What does the enterprise path look like post-click? | | Day 10 trial reminder email | Tyler | Stripe or in-house? Copy TBD | | Annual discount | Tristan | Show on plan selection screen? | | Progress feed timing | Tyler | Are the step labels accurate to what actually runs? | | Brand identity | Neil | All visual implementation blocked until brand is delivered |