Hire an AI developer architecture and onboarding writer

Everything it can hand back

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

• An architecture read: the parts, how they talk and where things live
• A README that records the decisions and their reasons
• An onboarding guide to the code and a quickstart to a running app
• A first-run test report with every step that broke

How it does the job well

• Turn every request into owned actions: who, what and by when.
• Work from the real calendar, notes and lists. Never invent meetings, people or dates.
• Put the most important decision or deadline first, then the details.
• Prepare drafts and proposals. Sending, booking and changing records waits for approval.

Mistakes it avoids

• Losing commitments buried in long notes.
• Mixing confirmed facts with guesses about other people's plans.
• Adding process when a short checklist would do.

What a good result looks like

An example, not your task: Someone starts in two weeks and the README is two years old.

• Architecture read. The parts of the codebase, how they talk, where things live and what is unusual, written for a newcomer.
• README. What the project is, each decision with its reason, and what not to change and why.
• Onboarding guide. Where to start reading, the main flows, the conventions and the gotchas.
• Quickstart. Each command from a clean machine to a running app, with the output to expect and what to do if not.
• First-run report. Each quickstart step marked passed or broke, with any assumed knowledge and a fix.
• HAND-BACK SUMMARY. Each step's file, any step not run and why, and every MISSING line in one list.

How the work is checked

• Each step passed its own checks, or the run stopped at the step that failed and says why.
• The steps ran in order, and each one used the result of the one before.
• Nothing was invented to fill a gap. Every gap is a MISSING: line.
• Nothing was sent, published or paid for without a clear yes.
• 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

• Read the architecture. Describes the parts of the codebase, how they talk and where things live, for a newcomer.
• Answer the interview. A pause. Answer its questions about why the code is shaped this way. Fifteen minutes is enough.
• Record the decisions. Interviews you for the decisions behind the structure and writes them into the README with their reasons.
• Write the onboarding guide. Writes a guide to the code: where to start reading, the main flows, conventions and gotchas.
• Write the quickstart. Writes the shortest path from a clean machine to a running app, with every command and expected output.
• Test the first run. Follows the quickstart as a newcomer would, checking each step against the code. It runs commands only if you say so, on a clean setup. It reports every step that breaks or assumes knowledge.

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 write-docs-a-new-developer-can-follow-on-day-one 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/write-docs-a-new-developer-can-follow-on-day-one/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 codebase, in a folder the AI can open
• Fifteen minutes to answer questions about the decisions behind it
• Who the new developer is and what they already know
• Your current README and docs, if any (optional)
• What the app is, its language, and the real install and run commands (optional)

Helpful context (optional)

• The contractor's or last developer's notes
• Your deploy and environment setup
• Past questions from new developers

Tools and access

• Claude Code or another coding agent: The steps read and change files in the project.
• A clean machine or container: The first-run test only means something on a setup without your local state.
• Claude or ChatGPT: Either can write the steps and outline. Neither can run your code, so test it yourself.
• Your own terminal: Running the quickstart on a clean machine is the only real test of it.

Functions and deliverables

• Developer architecture and onboarding writer: Share the codebase, setup access and team knowledge. Get an architecture guide, decision-backed README, quickstart and first-run report where tools allow.
  • An architecture read: the parts, how they talk and where things live
  • A README that records the decisions and their reasons
  • An onboarding guide to the code and a quickstart to a running app
  • A first-run test report with every step that broke
• Codebase architecture reviewer: Share your code. Get an HTML report of design improvements, then work through the one you pick.
  • An HTML report of design opportunities
  • Reasons for each
  • A short list ranked by payoff
  • A guided walkthrough of the one you choose
  Source: Matt Pocock.
• README and decision interviewer: Turn your project ideas into a README and short decision records. Your AI asks a few questions at a time and saves your answers as plain files.
  • README with the project vision
  • Decision records, one per choice
  • Reasons behind each decision
  • Updated docs after each session
  Source: sickn33.
• 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.
• Developer quickstart writer: Share the product, reader and setup facts. Get a short quickstart, tutorial or sample-app plan leading to a useful first result.
  • A one-line description of the first working result
  • A quickstart with prerequisites, 3 to 5 steps and the expected output
  • A tutorial outline for the second visit
  • A sample app plan with a minimal, starter and production version
  • The onboarding mistakes your product is most at risk of, with fixes
  • A list of what you still have to fill in
  Source: sickn33.
• README first-run tester: Check your README first-run steps against your repo. See each step marked working or broken, with proof and the edits that fix it.
  • Step list marked working, broken, missing or unchecked
  • Evidence with file and line
  • The real first-run path
  • README edits to fix problems
  Source: Pro Skill Packs.
• me.md builder: Answer a few questions, or let your AI use what it remembers. Get one private file that tells any AI who you are.
  • One me.md file with up to ten dated sections
  • A list of facts taken from memory, for you to check
  • A short note of what it removed for privacy
  • The two next steps, to save it and set it up

Tasks you can use it for

• Someone starts in two weeks and the README is two years old.
• You are the only person who knows why the code is shaped this way.
• Your last new developer took a month to run the app.

Limits to check before starting

• Your README is already current and nobody is joining soon: skip this and just update the README by hand.
• You need a guide for a business task, not code: write a plain checklist with a colleague who does the work.
• You have no codebase the AI can open, only an idea: sketch the plan with a teammate first.

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.

• Download the handoff pack. It's a zip with HANDOFF.md and the five skill files, in the order they run: Codebase architecture reviewer, README and decision interviewer, Codebase onboarding guide writer, Developer quickstart writer and README first-run tester.
• Give the folder to Claude (in Claude Code, or as files in a Claude Project) and say "Follow HANDOFF.md".
• Open the codebase in Claude Code and start. It reads the architecture and asks you about the decisions. If nobody can answer yet, each decision is marked MISSING in the README and nothing is guessed.
• Read the guide and the quickstart. Fix anything that is wrong about your setup.
• Read the first-run report and fix every broken step before the new developer starts.

Read it as data

Read the complete role setup as JSON. Connect your AI to the AI Blocks MCP library and read aiblocks://roles/write-docs-a-new-developer-can-follow-on-day-one 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.