Openstep

What inspired us

Contributing to open source is still harder than it should be. Issue trackers are noisy, “good first issue” labels don’t always match your languages, and it’s easy to stall after you pick an issue—especially if you’re learning alone. We wanted a single flow: understand what you already know from public GitHub activity, match you to issues that fit, then stay in one workspace (editor + context + mentor) instead of juggling ten tabs.

That aligned with the Auth0 × AI agents theme: different agents (Scout, Oracle, Sage, Forge, …) should each do one job clearly, with explicit permissions and safe boundaries—not one opaque model that “does everything.”

What we learned

Identity vs. data source: Users might sign in with one IdP (e.g. Google via Auth0) while Scout must target a GitHub handle for public repos and events. Separating “who is logged in” from “which GitHub account we analyze” reduced confusion and matched real product constraints.
Agent design: Small, composable backends (REST route per agent) are easier to reason about for judging and security than a monolithic “chat to the universe” endpoint.
Rate limits and honesty: GitHub search and REST quotas matter; optional GITHUB_TOKEN and clear UX (demo mode, empty states) make the demo reliable under hackathon pressure.
Mentoring stance: A Socratic mentor (Sage via Perplexity) fits onboarding better than dumping full solutions—while still allowing an opt-in path for more direct help where appropriate.

How we built it

Frontend: Next.js 16 (App Router), React 19, Tailwind 4—dashboard for Scout/Oracle/search, workspace with Monaco, maintainer flows where applicable.
Auth: Auth0 for sessions; optional M2M (x-agent-token) for machine clients where we wired it.
Data: Supabase (Postgres) for profiles, fingerprints, XP/badges/contributions.
Integrations: GitHub API for public profile signals and issue discovery; Perplexity for Sage/Solution-style agents; E2B for a sandbox terminal in Forge.

Conceptually, we treat “match quality” as something you can score and cap: if (s_i) is a simple relevance score for issue (i) and we show the top (k) results, we care about precision at small (k)—which is exactly the hackathon setting where users only skim a handful of cards:

[ \text{focus@}k = \frac{1}{k} \sum_{i=1}^{k} \mathbf{1}[\text{issue } i \text{ is truly actionable for this user}] ]

We didn’t ship a formal evaluator; the math is a design anchor: optimize the first screen of matches, not a thousand-row list.

Challenges we faced

Glue > greenfield: Wiring Auth0, Supabase, GitHub, Perplexity, and E2B with consistent error handling and env validation (check-env) took real time—most “bugs” were configuration and boundaries between server vs. client.
Schema vs. code drift: Contribution/ranker paths exposed mismatches between TypeScript inserts and the live schema; fixing that taught us to treat migrations and API routes as one contract.
Trust and safety: Deciding what goes into model prompts (structured context, no raw secrets), and surfacing agent permissions in the UI, was essential for a credible agent story.
Demo reliability: Empty states, loading states, and optional demo fingerprint mode so judges aren’t blocked if GitHub is slow or a user has thin public activity.

Where we’d take it next

Deeper maintainer loop (ratings → XP), richer “why matched” explanations, and tighter measurement of outcomes—issues opened, PRs merged, time-to-first-comment—so the product optimizes real contribution, not just clicks.