Hire an AI codebase onboarding planner

Everything it can hand back

Your task sets the actual outputs. The specialist picks the methods that cover them.

• A one-line statement of what the codebase is
• A five-minute explanation with the main tasks, inputs, outputs, key files and code paths
• A deep dive with the repo type, runtimes and entry points, and why each matters
• A table of top-level folders and what each one is for
• Step-by-step code paths with a file named at every step
• A list of files it opened, and the parts of the repo it did not read

How it does the job well

• Evidence. Never say a module owns a behavior unless you can point to the file that implements or routes it. If you did not open a file, do not describe it. Quote function, class, route, command and config key names exactly.
• Facts only. No opinions on quality, no refactoring ideas, no "you should" and no next steps inside the map. The "After this" question comes after you hand the map back. If the user asks for a review or a plan, say this role only describes the code, and suggest the Code Reviewer agent.
• Read-only. Do not edit files or write patches. Run a command only if the host gives you a shell and the command changes nothing, such as listing files or reading git log. Say which commands you ran.
• Partial reads. If you read only one part, say which files you read and which you did not. Never claim to understand the whole repo from one subsystem.
• Read the existing code, its conventions and its tests before changing anything. Match the project's patterns.
• Make the smallest change that fully solves the request. Keep unrelated refactors out.
• Reproduce a bug before fixing it, and add a test that fails without the fix.

Mistakes it avoids

• Claiming code works without running it or its tests.
• Inventing APIs, package versions or settings instead of checking the installed ones.
• Changing behaviour outside the request, such as reformatting whole files or renaming public interfaces.

What a good result looks like

An example, not your task: You start a new job or contract and must work in a repo you have never seen.

• 1-Line Summary. One sentence that says what the codebase is.
• 5-Minute Explanation. The main tasks, inputs, outputs, key files and the main code paths.
• Deep Dive. The repo type, runtimes and entry points, with why each one matters.
• Top-Level Structure. A table of folders with the purpose of each and a short note.
• Key Boundaries and Code Flows. Where screen, logic and storage code live, and numbered steps for each traced path.
• Files inspected. Every file it opened, and the parts of the repo it did not read.

How the work is checked

• The changed files build, and the relevant tests and linters pass. The commands and results are shown.
• Each change is explained in one line with its reason, and risky areas are named.
• Any check that could not run is reported as NOT_RUN with what it needs.
• States which checks passed, failed or could not run, and names missing inputs.

These checks have not been run against a model yet. Your AI uses them to check its own work.

Capabilities

• Inventory the repo. It reads manifests, lockfiles, build and deploy config and top-level folders. It decides if this is an app, library, monorepo, service or mix.
• Find the entry points. It looks for startup files, routers, handlers, CLI commands, workers and package exports. It picks the smallest set of files that show how the system starts.
• Trace real paths. It follows a request, event or command from input to output. It notes queues, cron jobs and background workers that change the flow.
• Mark the boundaries. It names where the screen, logic and storage code live. It notes public interfaces, shared code, dead code and misleading names it can see.
• Write three levels. It writes the one-line summary, the five-minute explanation and the deep dive, and lists every file it opened.

How the role works

1. Checks your task, context and available tools.
2. Picks the methods needed and prepares a work plan.
3. Carries out supported tasks, with each method's limits and review gates.
4. Checks the real deliverables and corrects supported faults.
5. Hands back files, evidence and unresolved gaps.

Your specialist's working setup

Download the base specialist without a task form or account. README.md and SETUP.md explain how to use the folder. SOUL.md defines its scope. INTAKE.md asks missing questions inside your AI. PLAYBOOK.md, SKILLS.md, BEST_PRACTICES.md, CHECKS.md and HANDOFF.md guide the work and its checked deliverables.

Complete associated skills, supporting files and licences are included. Choose only the methods needed for the actual task. Keep context, working files and accepted feedback in your AI project.

Use this specialist through MCP or the API

Call prepare_specialist with role_id engineering-codebase-onboarding-engineer only. No task is required to load it. Your AI asks what job you need done, what you want back and which relevant context it can use.

For task-led hiring, call find_specialist, explain the suggested specialists and let the user accept or change the team.

Complete ZIP: Download base specialist. API: GET /api/v1/specialists/engineering-codebase-onboarding-engineer/pack. The host AI supplies its own model, tools and execution; a pack does not connect accounts or run a task.

Inputs and helpful context

The specialist starts from the task brief. Only active methods require their inputs.

For the primary method, when used

• The repo, as files your AI can open, such as a folder, a zip, or a project open in Claude Code or Codex
• The question or goal, for example where to start or how a login request flows
• The part of the repo to focus on, such as one service in a monorepo (optional)
• What you already know, such as your main language, so terms are explained at your level (optional)

Helpful context (optional)

• One specific question beats "explain the repo". Ask for the path you will work on first.
• A list of folders to skip, such as generated code or vendored packages.

Tools and access

• Claude Code or Codex: They can open folders, search files and follow imports, so the map rests on real reads.
• Claude, ChatGPT or Gemini with a zip upload: They work for small and medium repos if you upload the folder instead of pasting snippets.

Functions and deliverables

• Codebase onboarding planner: Get a codebase onboarding map for any repo, with entry points, key files and how requests flow, built only from the code. Facts, no advice.
  • A one-line statement of what the codebase is
  • A five-minute explanation with the main tasks, inputs, outputs, key files and code paths
  • A deep dive with the repo type, runtimes and entry points, and why each matters
  • A table of top-level folders and what each one is for
  • Step-by-step code paths with a file named at every step
  • A list of files it opened, and the parts of the repo it did not read
  Source: Michael Sitarzewski and Agency Agents contributors.
• Codebase learning planner: Turn a code folder into a study map. Get ordered phases, what to know first and 2 or 3 paths that fit your goal and level.
  • An ordered map of learning phases.
  • A list of prerequisites and likely sticking points.
  • Two or three study paths with tradeoffs.
  Source: edu-agent-skills contributors.
• Codebase onboarding guide writer: Share a codebase. Get two guides that take a new engineer from first day to deep knowledge.
  • A senior-level onboarding guide
  • A getting-started guide
  • An architecture diagram
  • A log of key decisions
  Source: sickn33.
• Plain-text file reader code planner: Name a code file in your project. Claude Code explains it block by block in plain English, then sums up what the file does in one paragraph.
  • The file split into blocks, each with its line range, one of five labels and a plain English explanation
  • A one-paragraph summary: what the file is for, what goes in and what comes out
  • A short list of things this file does not show, such as which files call it
• AI project context organiser: Share your project and next task. Get a short rules file, a focused file list and a clear handoff for later sessions.
  • A ready rules file for your project
  • A list of which files to load for each task
  • Rules for when to reset or trim the session
  • A checklist for spotting drifting answers
  Source: Addy Osmani.

Tasks you can use it for

• You start a new job or contract and must work in a repo you have never seen.
• A client hands you code and asks you to take it over.
• You need to know where a feature lives before you change it, such as where checkout is handled.
• A new hire joins and you want a first map of the repo without writing the guide by hand.

Limits to check before starting

• You want to know if the code is good or safe to ship. Use the Code Reviewer agent or the Codebase architecture reviewer.
• You want to know why the code is inconsistent after many AI-assisted edits. Use the Codebase history researcher.
• You want a README or setup guide written for other people. Use the Engineering documentation writer.

Best way to use this role

Give it one clear outcome, the actual files and a definition of done. Keep the work in one AI project so it can reuse checked context and earlier files.

• Give your AI the code. A tool that opens folders works best, such as Claude Code or Codex, or a chat that accepts a zip. In a plain chat, paste the file tree and the main entry files.
• Add the pack as a skill, or paste SKILL.md and then references/source-agent.md into a new chat.
• Say what you want. For example, "Map this repo for a new developer. I want to understand how a signup request flows." Name a folder if the repo is large.
• Read the one-line summary and the five-minute section first. Then check the list of files inspected. Anything not on that list is not covered.
• Open the three or four files it names as the place to start. Check one code path against the real code.
• To go deeper, ask for one more path, such as the payment webhook, instead of asking it to explain everything.

Read it as data

Read the complete role setup as JSON. Connect your AI to the AI Blocks MCP library and read aiblocks://roles/engineering-codebase-onboarding-engineer for its role instructions and pinned sources.

This is a prepared AI role. No task has run. Your AI carries out authorized work using its available tools and reports the actual deliverables and checks.