Codebase Onboarding
Analyze any codebase and generate production-quality onboarding documentation tailored to the audience. Produces architecture overviews with system diagrams, annotated key file maps, step-by-step local setup guides, common developer task runbooks, debugging guides with real error solutions, and contribution guidelines. Supports Markdown, Notion, and Confluence output formats.
Core Capabilities
- Architecture analysis — tech stack identification from manifests/lockfiles, system boundary mapping, Mermaid data-flow diagrams, dependency graphs, module ownership.
- Key file annotation — surface the 20 most important files and why they matter; mark entry points, config hubs, shared utilities, and files dangerous to modify without coordination.
- Setup guide generation — prerequisites with exact versions,
git clone-to-tests steps, env-var docs, infra setup (Docker/DB/cache), and a verification checklist.
- Task runbooks — add an API endpoint, run/write tests, create & apply migrations, deploy to staging/production, add a dependency safely.
- Debugging guide — common errors with exact messages and fixes, log locations by environment, diagnostic SQL/CLI queries, local reproduction of production issues.
- Audience-aware output — tailored additions for junior developers, senior engineers, and contractors; Markdown / Notion / Confluence formats.
Keywords: codebase onboarding, developer experience, documentation, architecture overview, setup guide, debugging guide, contribution guidelines, code walkthrough, new hire onboarding
When to Use
- Onboarding a new team member (junior, senior, or contractor)
- After a major refactor that made existing docs stale
- Before open-sourcing a project
- Creating a team wiki page for a service you own
- Self-documenting before a long vacation or team transition
- Preparing for a compliance audit that requires documentation
Clarify First
Before generating the docs, confirm these inputs. If any is unknown or vague, ASK — do not assume:
Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.
Tools
| Tool |
Purpose |
Command |
architecture_mapper.py |
Analyze project structure and generate a high-level architecture map |
python scripts/architecture_mapper.py /path/to/project --json |
onboarding_generator.py |
Scan a project directory and generate an onboarding guide |
python scripts/onboarding_generator.py /path/to/project --json |
setup_validator.py |
Validate a project's development setup completeness |
python scripts/setup_validator.py /path/to/project --json |
All tools accept an optional directory argument (default: current directory) and --json for machine-readable output.
References
Load the reference that matches the task — keep this file lean and pull detail on demand:
- references/fact-gathering-and-patterns.md — the Phase 1 fact-gathering shell commands and the Phase 2 architecture-pattern classification table. Read when analyzing a codebase before writing docs.
- references/documentation-templates.md — the architecture overview, key file map, local setup, and debugging guide templates plus audience-specific (junior/senior/contractor) additions. Read when generating the actual onboarding documents.
- references/quality-and-best-practices.md — quality verification checklist, common pitfalls, best practices, a troubleshooting matrix, and success criteria. Read before shipping onboarding docs.
Scope & Limitations
This skill covers:
- Generating architecture overviews, key file maps, setup guides, task runbooks, and debugging guides from codebase analysis
- Audience-aware documentation tailored for junior developers, senior engineers, and contractors
- Output in Markdown, Notion, and Confluence formats
- Quality verification checklists and freshness audit processes
This skill does NOT cover:
- Automated API reference generation from code annotations — see
engineering/changelog-generator for release-oriented docs or engineering/api-design-reviewer for API quality
- Continuous documentation pipelines or CI-triggered doc builds — see
engineering/ci-cd-pipeline-builder for pipeline automation
- Security-focused documentation such as threat models or access control matrices — see
engineering/skill-security-auditor for security auditing
- Runbook generation for incident response and production operations — see
engineering/runbook-generator for operational runbooks
Integration Points
| Skill |
Integration |
Data Flow |
engineering/runbook-generator |
Onboarding task runbooks can seed operational runbooks for production incident response |
Onboarding runbook templates → Runbook Generator for ops-grade expansion |
engineering/api-design-reviewer |
API route analysis from Phase 1 feeds into API design quality reviews |
Discovered API endpoints → API Design Reviewer for consistency checks |
engineering/database-schema-designer |
Database schema files identified during key file mapping inform schema design reviews |
Schema file paths and ORM type → Schema Designer for migration planning |
engineering/tech-debt-tracker |
Technical debt items surfaced during architecture analysis should be logged for tracking |
Architecture analysis findings → Tech Debt Tracker backlog entries |
engineering/ci-cd-pipeline-builder |
CI/CD config discovered in Phase 1 can be validated and improved by the pipeline builder |
CI config paths and workflow list → Pipeline Builder for optimization |
engineering/dependency-auditor |
Dependency counts and lockfiles gathered in Phase 1 feed directly into security and license audits |
Package manifests and lockfiles → Dependency Auditor for vulnerability scanning |
1---2name: codebase-onboarding3description: Analyze a codebase and generate onboarding docs: architecture overviews, file maps, setup guides, runbooks, and debugging guides. Use when onboarding new team members, open-sourcing, or documenting after a major refactor.4license: MIT + Commons Clause5---6# Codebase Onboarding
7
8Analyze any codebase and generate production-quality onboarding documentation tailored to the audience. Produces architecture overviews with system diagrams, annotated key file maps, step-by-step local setup guides, common developer task runbooks, debugging guides with real error solutions, and contribution guidelines. Supports Markdown, Notion, and Confluence output formats.
9
10## Core Capabilities
11
12- **Architecture analysis** — tech stack identification from manifests/lockfiles, system boundary mapping, Mermaid data-flow diagrams, dependency graphs, module ownership.
13- **Key file annotation** — surface the 20 most important files and why they matter; mark entry points, config hubs, shared utilities, and files dangerous to modify without coordination.
14- **Setup guide generation** — prerequisites with exact versions, `git clone`-to-tests steps, env-var docs, infra setup (Docker/DB/cache), and a verification checklist.
15- **Task runbooks** — add an API endpoint, run/write tests, create & apply migrations, deploy to staging/production, add a dependency safely.
16- **Debugging guide** — common errors with exact messages and fixes, log locations by environment, diagnostic SQL/CLI queries, local reproduction of production issues.
17- **Audience-aware output** — tailored additions for junior developers, senior engineers, and contractors; Markdown / Notion / Confluence formats.
18
19**Keywords:** codebase onboarding, developer experience, documentation, architecture overview, setup guide, debugging guide, contribution guidelines, code walkthrough, new hire onboarding
20
21## When to Use
22
23- Onboarding a new team member (junior, senior, or contractor)
24- After a major refactor that made existing docs stale
25- Before open-sourcing a project
26- Creating a team wiki page for a service you own
27- Self-documenting before a long vacation or team transition
28- Preparing for a compliance audit that requires documentation
29
30## Clarify First
31
32Before generating the docs, confirm these inputs. If any is unknown or vague, ASK — do not assume:
33
34- [ ] **Target codebase path** — which project to analyze (the input all three scripts scan)
35- [ ] **Audience** — junior developer, senior engineer, or contractor (tailors which sections appear and at what depth)
36- [ ] **Output format** — Markdown, Notion, or Confluence (sets the generated document format)
37
38Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.
39
40## Tools
41
42| Tool | Purpose | Command |
43|------|---------|---------|
44| `architecture_mapper.py` | Analyze project structure and generate a high-level architecture map | `python scripts/architecture_mapper.py /path/to/project --json` |
45| `onboarding_generator.py` | Scan a project directory and generate an onboarding guide | `python scripts/onboarding_generator.py /path/to/project --json` |
46| `setup_validator.py` | Validate a project's development setup completeness | `python scripts/setup_validator.py /path/to/project --json` |
47
48All tools accept an optional `directory` argument (default: current directory) and `--json` for machine-readable output.
49
50## References
51
52Load the reference that matches the task — keep this file lean and pull detail on demand:
53
54- **[references/fact-gathering-and-patterns.md](references/fact-gathering-and-patterns.md)** — the Phase 1 fact-gathering shell commands and the Phase 2 architecture-pattern classification table. Read when analyzing a codebase before writing docs.
55- **[references/documentation-templates.md](references/documentation-templates.md)** — the architecture overview, key file map, local setup, and debugging guide templates plus audience-specific (junior/senior/contractor) additions. Read when generating the actual onboarding documents.
56- **[references/quality-and-best-practices.md](references/quality-and-best-practices.md)** — quality verification checklist, common pitfalls, best practices, a troubleshooting matrix, and success criteria. Read before shipping onboarding docs.
57
58## Scope & Limitations
59
60**This skill covers:**
61- Generating architecture overviews, key file maps, setup guides, task runbooks, and debugging guides from codebase analysis
62- Audience-aware documentation tailored for junior developers, senior engineers, and contractors
63- Output in Markdown, Notion, and Confluence formats
64- Quality verification checklists and freshness audit processes
65
66**This skill does NOT cover:**
67- Automated API reference generation from code annotations — see `engineering/changelog-generator` for release-oriented docs or `engineering/api-design-reviewer` for API quality
68- Continuous documentation pipelines or CI-triggered doc builds — see `engineering/ci-cd-pipeline-builder` for pipeline automation
69- Security-focused documentation such as threat models or access control matrices — see `engineering/skill-security-auditor` for security auditing
70- Runbook generation for incident response and production operations — see `engineering/runbook-generator` for operational runbooks
71
72## Integration Points
73
74| Skill | Integration | Data Flow |
75|-------|------------|-----------|
76| `engineering/runbook-generator` | Onboarding task runbooks can seed operational runbooks for production incident response | Onboarding runbook templates → Runbook Generator for ops-grade expansion |
77| `engineering/api-design-reviewer` | API route analysis from Phase 1 feeds into API design quality reviews | Discovered API endpoints → API Design Reviewer for consistency checks |
78| `engineering/database-schema-designer` | Database schema files identified during key file mapping inform schema design reviews | Schema file paths and ORM type → Schema Designer for migration planning |
79| `engineering/tech-debt-tracker` | Technical debt items surfaced during architecture analysis should be logged for tracking | Architecture analysis findings → Tech Debt Tracker backlog entries |
80| `engineering/ci-cd-pipeline-builder` | CI/CD config discovered in Phase 1 can be validated and improved by the pipeline builder | CI config paths and workflow list → Pipeline Builder for optimization |
81| `engineering/dependency-auditor` | Dependency counts and lockfiles gathered in Phase 1 feed directly into security and license audits | Package manifests and lockfiles → Dependency Auditor for vulnerability scanning |
borghei