{
 "schema": "aiblocks-page/1",
 "id": "agency-engineering-codebase-onboarding-engineer",
 "type": "agent",
 "name": "Codebase onboarding planner",
 "summary": "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.",
 "headline": "Codebase onboarding planner",
 "subhead": "Point your AI at a repository and ask where to start. It reads the code and traces how a request or command moves through it. You get a three-level map with file paths, built only from files it opened.",
 "job": {
  "id": "document-work",
  "name": "Write down how work gets done"
 },
 "level": "intermediate",
 "thinking": "high",
 "tested": true,
 "updated": "2026-11-03",
 "first_published": "2026-10-26",
 "inputs": [
  {
   "type": "codebase",
   "required": true,
   "label": "Codebase",
   "what": "a project's code, in a folder or repo the AI can open"
  },
  {
   "type": "question",
   "required": false,
   "label": "Question",
   "what": "the problem, decision or piece of work you want help with, and what a good outcome looks like"
  }
 ],
 "outputs": [
  {
   "type": "document",
   "required": true,
   "label": "Document",
   "what": "a finished document, such as a Word file, a PDF or a page of notes"
  }
 ],
 "you_give": [
  "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)"
 ],
 "you_get": [
  "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"
 ],
 "use_when": [
  "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."
 ],
 "skip_when": [
  "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."
 ],
 "output_sample": {
  "input": [
   "Your repository, as a folder, zip or open project",
   "The question or area to focus on",
   "Your main language or experience (optional)"
  ],
  "prerequisites": [
   "An AI that can open files, such as Claude Code, Codex or a chat that takes a zip"
  ],
  "output": [
   {
    "name": "1-Line Summary",
    "contains": "One sentence that says what the codebase is."
   },
   {
    "name": "5-Minute Explanation",
    "contains": "The main tasks, inputs, outputs, key files and the main code paths."
   },
   {
    "name": "Deep Dive",
    "contains": "The repo type, runtimes and entry points, with why each one matters."
   },
   {
    "name": "Top-Level Structure",
    "contains": "A table of folders with the purpose of each and a short note."
   },
   {
    "name": "Key Boundaries and Code Flows",
    "contains": "Where screen, logic and storage code live, and numbered steps for each traced path."
   },
   {
    "name": "Files inspected",
    "contains": "Every file it opened, and the parts of the repo it did not read."
   }
  ]
 },
 "output_shape": "# Codebase Orientation Map\n\n## 1-Line Summary\n<one sentence: what this codebase is>\n\n## 5-Minute Explanation\n- Primary tasks in code: <what the code does>\n- Primary inputs: <requests, CLI arguments, messages, files>\n- Primary outputs: <responses, database writes, files, events, screens>\n- Key files: <path and its job>\n- Main code paths: <entry -> orchestration -> core logic -> outputs>\n\n## Deep Dive\n- Type: <web app, API, monorepo, CLI, library or mix>\n- Runtimes: <Node.js, Python, Go, browser and so on>\n- Entry points: <path and why it matters>\n- Top-level structure: <table of path, purpose, notes>\n- Key boundaries: <screen, logic, storage, shared code, with files>\n- Detailed code flows: <numbered steps, each with a file path>\n- How the pieces map together: <imports, calls, handlers, storage>\n- Files inspected: <full list>\n- Not inspected: <parts of the repo not read>",
 "how_to_use": [
  "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."
 ],
 "checks": [
  "The result addresses your actual task and cites the evidence used.",
  "Examples, role-play experience and targets are kept separate from verified results.",
  "Claims of tests, memory, tool access or completed actions match what actually happened."
 ],
 "next": [
  {
   "name": "Codebase history researcher",
   "url": "https://useaiblocks.com/skills/agency-specialized-codebase-archaeologist",
   "why": "Codebase history researcher"
  },
  {
   "name": "Data catalog entry writer",
   "url": "https://useaiblocks.com/skills/data-catalog-entry-writer",
   "why": "Data catalog entry writer"
  }
 ],
 "source": {
  "by": "Michael Sitarzewski and Agency Agents contributors",
  "repo": "msitarzewski/agency-agents",
  "url": "https://github.com/msitarzewski/agency-agents/blob/b37b5bb33b78f2c1d6567d98e25ca818e3259219/engineering/engineering-codebase-onboarding-engineer.md",
  "licence": "MIT",
  "original_name": "Codebase Onboarding Engineer",
  "commit": "b37b5bb33b78f2c1d6567d98e25ca818e3259219"
 },
 "credits": [
  {
   "title": "Codebase Onboarding Engineer",
   "by": "Michael Sitarzewski and Agency Agents contributors",
   "url": "https://github.com/msitarzewski/agency-agents/blob/b37b5bb33b78f2c1d6567d98e25ca818e3259219/engineering/engineering-codebase-onboarding-engineer.md",
   "used": "Original agent profile, preserved in references/source-agent.md; AI Blocks adds setup and review instructions."
  }
 ],
 "files": [
  "LICENSE",
  "references/source-agent.md",
  "SETUP.md",
  "source.json"
 ],
 "links": {
  "page": "https://useaiblocks.com/agents/agency-engineering-codebase-onboarding-engineer",
  "markdown": "https://useaiblocks.com/agents/agency-engineering-codebase-onboarding-engineer.md",
  "json": "https://useaiblocks.com/agents/agency-engineering-codebase-onboarding-engineer.json",
  "instructions": "https://useaiblocks.com/skills/agency-engineering-codebase-onboarding-engineer/SKILL.md",
  "download": "https://useaiblocks.com/skills/agency-engineering-codebase-onboarding-engineer.zip",
  "api_item": "https://useaiblocks.com/api/v1/items/agency-engineering-codebase-onboarding-engineer",
  "api_document": "https://useaiblocks.com/api/v1/documents/agent/agency-engineering-codebase-onboarding-engineer",
  "mcp": "https://useaiblocks.com/mcp"
 }
}