workflow-onboard — Codebase Orientation
Degree of freedom: MIXED. Briefing synthesis [HIGH freedom]; which files
to read and never printing env values [LOW freedom — run exactly].
Orient to any repo in under 5 minutes. Read first, explain second.
How to reason
- Read — manifests, routes, schema, auth — don't guess
- Map — stack, features, data, how-to-run
- Gap — missing README/schema said out loud
- Brief — scannable; top-3 complexity called out
Worked example
Read: package.json is Next.js 16 + Supabase; src/app/(app)/* has dashboard, billing, settings; latest migration adds organizations.
Map: B2B dashboard; session via middleware + getUser(); run pnpm dev.
Gap: no README scripts section; .env.example lists STRIPE_SECRET_KEY.
Brief: purpose + stack + route map + 4 tables + auth + pnpm dev + env names + "start in src/lib/billing".
Self-critique before reporting
- Files read — briefing cites files, not folklore
- Secrets safe — env names only, never values
- Gaps explicit — missing schema/README is stated, not invented
- Right owner — preflight commands/services →
workflow-environment-ready; parked work → housekeep-backlog
Step 1: Stack & entry points [LOW freedom — run exactly]
Read (do not shell-grep unless necessary):
| File |
What to extract |
package.json / pyproject.toml / Cargo.toml |
Runtime, framework, key deps, scripts |
README.md |
Stated purpose, setup steps, architecture notes |
src/app/layout.tsx / pages/_app.tsx / App.tsx |
Root component, providers, global context |
src/app/**/page.tsx / src/routes/** / app/routes/** |
Route tree → feature map |
capacitor.config.* / app.json / app.config.* |
Mobile targets (Expo/RN/Capacitor) |
android/ / ios/ presence |
Native targets |
Step 2: Data & auth layer [LOW freedom — run exactly]
| File |
What to extract |
supabase/migrations/*.sql (latest 3) |
Schema, tables, relationships |
prisma/schema.prisma / drizzle/*.ts |
ORM model |
src/lib/supabase.* / src/lib/db.* |
Client init, auth helper |
.env.example / .env.local (names only, never values) |
Required env vars |
middleware.ts / auth.ts / src/lib/auth.* |
Auth guard pattern |
Step 3: Recent context [LOW freedom — run exactly]
git log --oneline -15 # recent work direction
git diff HEAD~5 --stat # files changed recently
Step 4: Orientation briefing [HIGH freedom]
Produce a structured briefing covering:
- What it is — one sentence on the product's purpose
- Tech stack — framework + DB + auth + mobile targets
- Feature map — top-level routes grouped by capability
- Data model — key entities and relationships (3-5 tables max)
- Auth pattern — how sessions work and who the roles are
- How to run — exact commands from
package.json scripts
- Environment — required env vars (names only) and where to find values
- Top 3 to understand first — the areas with the most business logic or complexity
Format as a scannable briefing, not a wall of text. Use short tables where helpful.
Guardrails [LOW freedom — do not skip]
- Never print
.env values — names only
- If the codebase is a monorepo, scope the briefing to the specific app/package the user is working in (ask if unclear)
- If critical files are missing (no README, no schema), say so explicitly rather than guessing
1---2name: workflow-onboard-23description: First-contact orientation for an unfamiliar codebase. Use when "I'm new to this repo", "orient me", "explain this codebase", "what does this do?", "onboard me", "first day on this project", or "catch me up on the codebase".4license: MIT5---67# workflow-onboard — Codebase Orientation89**Degree of freedom: MIXED.** Briefing synthesis `[HIGH freedom]`; which files10to read and never printing env values `[LOW freedom — run exactly]`.1112Orient to any repo in under 5 minutes. Read first, explain second.1314## How to reason15161. **Read** — manifests, routes, schema, auth — don't guess172. **Map** — stack, features, data, how-to-run183. **Gap** — missing README/schema said out loud194. **Brief** — scannable; top-3 complexity called out2021## Worked example2223> **Read:** `package.json` is Next.js 16 + Supabase; `src/app/(app)/*` has dashboard, billing, settings; latest migration adds `organizations`.24> **Map:** B2B dashboard; session via middleware + `getUser()`; run `pnpm dev`.25> **Gap:** no README scripts section; `.env.example` lists `STRIPE_SECRET_KEY`.26> **Brief:** purpose + stack + route map + 4 tables + auth + `pnpm dev` + env names + "start in `src/lib/billing`".2728## Self-critique before reporting2930- **Files read** — briefing cites files, not folklore31- **Secrets safe** — env names only, never values32- **Gaps explicit** — missing schema/README is stated, not invented33- **Right owner** — preflight commands/services → `workflow-environment-ready`; parked work → `housekeep-backlog`3435---3637## Step 1: Stack & entry points [LOW freedom — run exactly]3839Read (do not shell-grep unless necessary):4041| File | What to extract |42|------|-----------------|43| `package.json` / `pyproject.toml` / `Cargo.toml` | Runtime, framework, key deps, scripts |44| `README.md` | Stated purpose, setup steps, architecture notes |45| `src/app/layout.tsx` / `pages/_app.tsx` / `App.tsx` | Root component, providers, global context |46| `src/app/**/page.tsx` / `src/routes/**` / `app/routes/**` | Route tree → feature map |47| `capacitor.config.*` / `app.json` / `app.config.*` | Mobile targets (Expo/RN/Capacitor) |48| `android/` / `ios/` presence | Native targets |4950---5152## Step 2: Data & auth layer [LOW freedom — run exactly]5354| File | What to extract |55|------|-----------------|56| `supabase/migrations/*.sql` (latest 3) | Schema, tables, relationships |57| `prisma/schema.prisma` / `drizzle/*.ts` | ORM model |58| `src/lib/supabase.*` / `src/lib/db.*` | Client init, auth helper |59| `.env.example` / `.env.local` (names only, never values) | Required env vars |60| `middleware.ts` / `auth.ts` / `src/lib/auth.*` | Auth guard pattern |6162---6364## Step 3: Recent context [LOW freedom — run exactly]6566```bash67git log --oneline -15 # recent work direction68git diff HEAD~5 --stat # files changed recently69```7071---7273## Step 4: Orientation briefing [HIGH freedom]7475Produce a structured briefing covering:76771. **What it is** — one sentence on the product's purpose782. **Tech stack** — framework + DB + auth + mobile targets793. **Feature map** — top-level routes grouped by capability804. **Data model** — key entities and relationships (3-5 tables max)815. **Auth pattern** — how sessions work and who the roles are826. **How to run** — exact commands from `package.json` scripts837. **Environment** — required env vars (names only) and where to find values848. **Top 3 to understand first** — the areas with the most business logic or complexity8586Format as a scannable briefing, not a wall of text. Use short tables where helpful.8788---8990## Guardrails [LOW freedom — do not skip]9192- Never print `.env` values — names only93- If the codebase is a monorepo, scope the briefing to the specific app/package the user is working in (ask if unclear)94- If critical files are missing (no README, no schema), say so explicitly rather than guessing
kensaurus