{ "schema": "aiblocks-page/1", "id": "agency-specialized-codebase-archaeologist", "type": "agent", "name": "Codebase history researcher", "summary": "Find silent mismatches in code built over many AI sessions, such as reversed fallbacks, duplicate logic and stale docs, ranked by risk with files named.", "headline": "Codebase history researcher", "subhead": "Give your AI a repo and its history. It looks for places where one file assumes something another file changed, such as two helpers that disagree. You get a drift registry with every finding tied to files, a risk level and the likely cause.", "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" }, { "type": "document", "required": false, "label": "Document", "what": "a finished document, such as a Word file, a PDF or a page of notes" } ], "outputs": [ { "type": "audit_report", "required": true, "label": "Audit report", "what": "findings with evidence, severity, missing inputs and next actions" } ], "you_give": [ "The repo, as files your AI can open, such as a folder, a zip or a project open in Claude Code", "The git history, or the output of git log with dates (optional but it makes the eras far clearer)", "Where to look, such as orders and payments, or the whole repo", "Your README and docs, to compare with the code (optional)", "Any earlier drift registry, so this run can check what stayed fixed (optional)" ], "you_get": [ "A drift registry with four views, by finding, by era, by responsibility and by risk", "Each finding with the files, the failure it could cause, a severity and its likely origin", "A list of event handlers checked, marked safe or unguarded", "A list of money and quantity values traced, with the unit at each step", "Dead code, doc-versus-code mismatches and a cleanup order", "A list of the files it read and the ones it did not" ], "use_when": [ "A project grew over months with several AI coding tools, and you do not trust that the parts agree.", "Money, orders or stock numbers come out slightly wrong and no single bug explains it.", "You inherited a codebase and want to know what was half-migrated and left behind.", "Before a big refactor, you want to know which files are safe to build on." ], "skip_when": [ "You are new to a repo and want to know how it is laid out. Use the Codebase onboarding planner.", "You want a code review of a pull request or one file. Use the Code Reviewer agent or the Bug and security code reviewer.", "You want to find out where docs no longer match one feature. Use the Code and documentation consistency checker.", "Something is broken in production now. Debug it first, then use this for the wider cleanup." ], "output_sample": { "input": [ "Your repo, as a folder, zip or open project", "The git log with dates (optional)", "The area to audit, such as orders and payments", "Your README and docs (optional)" ], "prerequisites": [ "An AI that can open files, such as Claude Code, Codex or a chat that takes a zip" ], "output": [ { "name": "Drift registry", "contains": "Four cross-linked views of every finding, by finding, by era, by responsibility and by risk." }, { "name": "Finding detail", "contains": "For each serious finding, the files, what each side does, the risk and the likely origin." }, { "name": "Checked and safe", "contains": "Handlers and values it checked and found safe, so you know they were covered." }, { "name": "Dead code", "contains": "Files with no remaining references and the thing that replaced them." }, { "name": "Doc versus code", "contains": "Each doc claim that no longer matches the code, with what the code does now." }, { "name": "Cleanup order", "contains": "Critical, moderate and cosmetic items in the order to fix them." } ] }, "output_shape": "DRIFT REGISTRY\n Scope: | Files read: | Not read: \n\nVIEW 1, BY FINDING\n | | | | \n\nVIEW 2, BY ERA\n | | | \n\nVIEW 3, BY RESPONSIBILITY\n | | \n\nVIEW 4, BY RISK\n Critical: | Moderate: | Cosmetic: \n\nFINDING DETAIL (one per critical or moderate finding)\n Files: | Pattern found: | Risk: | Likely origin: | Fix direction: \n\nCHECKED AND SAFE\n | \n\nDEAD CODE\n | | \n\nDOC VERSUS CODE\n | | \n\nCLEANUP ORDER\n Critical: | Moderate: | Cosmetic: ", "how_to_use": [ "Give your AI the code. A tool that opens folders and runs git works best, such as Claude Code or Codex. Both need a paid plan or account. A plain chat works without one, but you must paste the git log, the file list and the files you suspect.", "Add the pack as a skill, or paste SKILL.md and then references/source-agent.md into a new chat.", "Say where to look. For example, \"Audit the orders and payments code for drift. Here is the git log.\" Pick one area on a large repo.", "Read the critical findings first. For each one, open both files and check that the mismatch is real.", "Fix one finding at a time, in both files. Then rerun with the registry attached to see that it stayed fixed.", "Hand confirmed findings to a person or tool that can edit the code. This agent does not change files." ], "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": "Developer docs writer", "url": "https://useaiblocks.com/skills/developer-docs-writer", "why": "Developer docs writer" }, { "name": "Process guide revision reviewer", "url": "https://useaiblocks.com/skills/process-doc-freshness-keeper", "why": "Process guide revision reviewer" } ], "source": { "by": "Michael Sitarzewski and Agency Agents contributors", "repo": "msitarzewski/agency-agents", "url": "https://github.com/msitarzewski/agency-agents/blob/b37b5bb33b78f2c1d6567d98e25ca818e3259219/specialized/specialized-codebase-archaeologist.md", "licence": "MIT", "original_name": "Codebase Archaeologist", "commit": "b37b5bb33b78f2c1d6567d98e25ca818e3259219" }, "credits": [ { "title": "Codebase Archaeologist", "by": "Michael Sitarzewski and Agency Agents contributors", "url": "https://github.com/msitarzewski/agency-agents/blob/b37b5bb33b78f2c1d6567d98e25ca818e3259219/specialized/specialized-codebase-archaeologist.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-specialized-codebase-archaeologist", "markdown": "https://useaiblocks.com/agents/agency-specialized-codebase-archaeologist.md", "json": "https://useaiblocks.com/agents/agency-specialized-codebase-archaeologist.json", "instructions": "https://useaiblocks.com/skills/agency-specialized-codebase-archaeologist/SKILL.md", "download": "https://useaiblocks.com/skills/agency-specialized-codebase-archaeologist.zip", "api_item": "https://useaiblocks.com/api/v1/items/agency-specialized-codebase-archaeologist", "api_document": "https://useaiblocks.com/api/v1/documents/agent/agency-specialized-codebase-archaeologist", "mcp": "https://useaiblocks.com/mcp" } }