From clarc
Generates onboarding documentation for an existing codebase: README, CONTRIBUTING.md, architecture overview/tour, domain glossary, setup validation, and GitHub issue template.
How this command is triggered — by the user, by Claude, or both
Slash command
/clarc:onboardThe summary Claude sees in its command listing — used to decide when to auto-load this command
# Onboard Read an existing codebase and generate accurate onboarding documentation: README, CONTRIBUTING.md, Architecture Overview, Architecture Tour, Domain Glossary, and Onboarding Issue Template. ## Instructions ### 1. Parse Arguments and Read the Codebase `$ARGUMENTS` controls scope: - (empty) → full onboarding suite - `readme` → only README.md - `contributing` → only CONTRIBUTING.md - `architecture` → delegate to `/arc42` (arc42 + C4 diagrams) - `tour` → only Architecture Tour (step 5) - `glossary` → only Domain Glossary (step 6) - `checklist` → only GitHub Onboarding Issue Templat...
Read an existing codebase and generate accurate onboarding documentation: README, CONTRIBUTING.md, Architecture Overview, Architecture Tour, Domain Glossary, and Onboarding Issue Template.
$ARGUMENTS controls scope:
readme → only README.mdcontributing → only CONTRIBUTING.mdarchitecture → delegate to /arc42 (arc42 + C4 diagrams)tour → only Architecture Tour (step 5)glossary → only Domain Glossary (step 6)checklist → only GitHub Onboarding Issue Template (step 7)setup → only setup script audit (step 4)all → all documentsExplore the project thoroughly before writing anything:
Files to read:
- Top-level directory structure
- package.json / pyproject.toml / go.mod / pom.xml / Cargo.toml
→ project name, scripts, dependencies, language version
- Entry point: main.ts / main.py / main.go / Application.java / src/app.ts
- Key modules and their responsibilities (read directory names + key files)
- Database schema: prisma/schema.prisma / migrations/ / models.py
- API routes: routes/ / controllers/ / handlers/ / openapi.yaml
- External services: .env.example / config/ / docker-compose.yml
- Test setup: jest.config / pytest.ini / go test / pom.xml surefire
- CI/CD: .github/workflows/ / .gitlab-ci.yml / Makefile
- Existing docs: README.md / CONTRIBUTING.md / docs/
- Setup script: scripts/setup.sh / Makefile setup target
Use Glob and Read to analyse the codebase — do NOT run arbitrary Bash commands on it. Write is permitted for generating output files.
Determine:
If README.md exists and is comprehensive, report what's already there and skip. Otherwise add missing sections:
# <Project Name>
<1-2 sentence description of what this is and what it does>
## What It Does
<3-5 bullet points of key features/capabilities>
## Architecture Overview
<1 paragraph: the main components and how they fit together>
See [docs/architecture/arc42.md](./docs/architecture/arc42.md) for the full picture.
## Getting Started
### Prerequisites
| Tool | Version | Install |
|------|---------|---------|
<list based on actual runtime requirements detected>
### Setup
```bash
git clone https://github.com/<org>/<repo>.git
cd <repo>
<actual setup command — ./scripts/setup.sh or make setup or npm install>
<actual test command from package.json / Makefile / pyproject.toml>
| Command | Description |
|---|---|
<command> | <from package.json scripts / Makefile / pyproject.toml> |
See .env.example for all required variables.
See CONTRIBUTING.md.
---
### 3. Generate CONTRIBUTING.md
Generate a CONTRIBUTING.md that is specific to this project's actual tools and conventions — not generic boilerplate.
```markdown
# Contributing to <Project Name>
## Prerequisites
| Tool | Version | Install |
|------|---------|---------|
<detected tools with exact versions from config files>
## Setup (one-time)
```bash
git clone https://github.com/<org>/<repo>.git
cd <repo>
<actual setup command>
Setup takes about X minutes. See Troubleshooting if anything fails.
# Start the development environment
<actual dev command>
# Run all tests
<actual test command>
# Type check and lint
<actual check command>
main: git checkout -b feat/your-feature<check command> passes before opening a PRfeat:, fix:, docs:, refactor:, test:Language:
Formatter: — runs automatically on save (editor settings included if found)
Linter: — <lint command>
Type checker:
Coverage: 80% minimum on new code
Use Conventional Commits:
feat: — new featurefix: — bug fixrefactor: — refactoring (no behavior change)test: — tests onlydocs: — documentation onlychore: — tooling, dependencies<test command>)<lint command>)<actual directory structure — read top-level dirs + key files>
See docs/architecture/arc42.md for the full arc42 architecture document.
Key files every developer should know: <list 5-10 anchor files from the codebase>
Major decisions are documented as ADRs in docs/decisions/. Read these before asking "why is it this way?".
---
### 4. Audit the Setup Script
Find the setup script (`scripts/setup.sh` / `Makefile setup` / `package.json postinstall` / etc.) and evaluate it against these criteria:
| Criterion | Check |
|-----------|-------|
| **Exists** | Is there a one-command bootstrap? |
| **Idempotent** | Can it be run twice safely? Look for `[ -f .env ] \|\| cp .env.example .env` patterns |
| **Fast** | Estimates time — no unnecessary downloads or rebuilds |
| **Actionable errors** | Uses `|| fail "message: install X via Y"` pattern |
| **Cross-platform** | Handles macOS vs Linux differences |
| **Doctor command** | Is there a `make doctor` or `./scripts/check.sh` for ongoing health checks? |
| **Version checks** | Validates required tool versions, not just presence |
Report findings as PASS / WARN / FAIL per criterion with suggested fixes.
If no setup script exists, generate a skeleton based on the detected stack:
```bash
# scripts/setup.sh skeleton generated by /onboard
#!/usr/bin/env bash
set -euo pipefail
fail() { echo "✗ $*" >&2; exit 1; }
ok() { echo "✓ $*"; }
# 1. Check tools
command -v <runtime> >/dev/null 2>&1 || fail "<Runtime> not found. Install via: <instructions>"
ok "<Runtime> $(<runtime> --version)"
# 2. Install dependencies
<package manager install command>
ok "Dependencies installed"
# 3. Configure environment
[ -f .env ] || cp .env.example .env && ok "Created .env — review required values"
# 4. Start services
<docker compose up -d or equivalent>
ok "Services started"
# 5. Migrate database (if applicable)
<migration command>
ok "Database ready"
echo "Setup complete. Run: <dev command>"
An Architecture Tour explains the codebase through the lens of a real, concrete user action — tracing a request end-to-end:
Identify the most important user flow (e.g., creating a resource, logging in, processing a payment) by reading the routes and services.
# Architecture Tour: What happens when a user <does X>?
## Overview
<1 paragraph description of the system and the flow being traced>
## Step 1 — <First layer, e.g. HTTP Request>
**File:** `<actual file path>`
- <What this file does in this flow>
- <Key decision or pattern used here>
## Step 2 — <Second layer, e.g. Business Logic>
**File:** `<actual file path>`
- <What this file does>
- <Dependencies it calls>
## Step 3 — <Third layer, e.g. Persistence>
**File:** `<actual file path>`
- <Database interaction>
- <Transaction or consistency pattern>
## Step 4 — <Async or side effects, if applicable>
**File:** `<actual file path>`
- <Background job, event, webhook, email, etc.>
## Tests for this flow
| Layer | Test file |
|-------|-----------|
| Unit | `<path>` |
| Integration | `<path>` |
| E2E | `<path>` (if present) |
## Key Files Every Developer Should Know
| File | Purpose |
|------|---------|
<list 5-10 anchor files identified from the codebase>
Extract domain-specific terminology from the codebase:
src/domain/ or equivalent (value objects, aggregates)src/constants.ts or equivalentdocs/decisions/ for important conceptsGenerate:
# Domain Glossary
Terms that are specific to this system and may not be obvious to a new developer.
| Term | Definition |
|------|-----------|
| **<Term>** | <Definition derived from code and comments> |
| **<Term>** | <Definition> |
If fewer than 5 domain terms are found, note that and add a placeholder for the team to fill in.
<!-- .github/ISSUE_TEMPLATE/onboarding.md -->
---
name: Developer Onboarding
about: Track onboarding progress for a new team member
title: 'Onboarding: [Name]'
labels: onboarding
assignees: ''
---
## Welcome to <Project Name>!
Buddy assigned: @___
Start date: ___
## Week 1 — Setup & First PR
- [ ] Local environment running (`<setup command>` succeeded)
- [ ] All tests passing locally (`<test command>`)
- [ ] Read [CONTRIBUTING.md](./CONTRIBUTING.md)
- [ ] Completed Architecture Tour (`docs/onboarding/architecture-tour.md`)
- [ ] Reviewed 5 recent merged PRs to understand coding style
- [ ] First PR merged (can be a documentation fix or good-first-issue)
## Week 2 — First Bug Fix
- [ ] Read Architecture Decision Records in `docs/decisions/`
- [ ] Completed a Code Archaeology session with buddy (git blame, hotspot analysis)
- [ ] First bug fix PR opened and merged independently
- [ ] Can write and run tests without help
## Week 3–4 — First Feature
- [ ] First feature ticket picked from backlog
- [ ] ADR drafted (if architectural decision was needed)
- [ ] Feature implemented with tests (TDD workflow)
- [ ] Feature deployed to staging and verified
## Feedback (after 30 days)
Please share your onboarding experience so we can improve it for the next hire:
[ ] Submitted onboarding feedback
Save this file to .github/ISSUE_TEMPLATE/onboarding.md.
Architecture documentation follows the arc42 standard with C4 diagrams. Delegate to the /arc42 command:
/arc42 all
This generates:
docs/architecture/arc42.md — full 12-section arc42 documentdocs/architecture/diagrams/context.puml — C4 Contextdocs/architecture/diagrams/container.puml — C4 Containerdocs/architecture/diagrams/component-api.puml — C4 Componentdocs/architecture/diagrams/deployment.puml — C4 DeploymentIf /arc42 was already run (arc42.md exists), skip and report.
If the project has a legacy
ARCHITECTURE.mdin the root, offer to migrate: "Found ARCHITECTURE.md. Migrate to arc42 in docs/architecture/arc42.md? (yes/no)"
DEVELOPER ONBOARDING ARTIFACTS GENERATED
══════════════════════════════════════════
Project: <name>
Language: <detected>
Framework: <detected>
Generated:
README.md ← <new | updated | skipped (already complete)>
CONTRIBUTING.md ← <new | updated>
scripts/setup.sh ← <new skeleton | audit report>
docs/onboarding/architecture-tour.md ← <new>
docs/onboarding/glossary.md ← <new — N terms>
.github/ISSUE_TEMPLATE/onboarding.md ← <new>
docs/architecture/arc42.md ← <new — arc42 + C4 diagrams>
Setup script audit:
Idempotent: <PASS | WARN | FAIL>
Fast (< 5 min): <PASS | WARN | FAIL>
Cross-platform: <PASS | WARN | FAIL>
Doctor command: <PASS | MISSING>
Architecture highlights:
- Request flow traced: <user action>
- Anchor files identified: <N>
- Domain terms documented: <N>
- ADRs indexed: <N>
Next steps:
1. Fill in .env values required for local development
2. Review and customise the onboarding GitHub Issue Template
3. Assign a buddy to the next new hire and create their onboarding issue
developer-onboarding — code archaeology, setup script design, CONTRIBUTING.md patterns, onboarding metricsarc42-c4 — architecture documentation with C4 diagramsadr-writing — Architecture Decision Records/tdd — validate the setup script works on a clean environment/setup-dev — run the generated setup scriptnpx claudepluginhub marvinrichter/clarc --plugin clarc/onboardGenerates four audience-tailored onboarding guides—Contributor, Staff Engineer, Executive, Product Manager—in an onboarding/ folder with index hub.
/onboardGenerates a developer onboarding guide by scanning project configs, structure, and docs for prerequisites, setup, workflow, key concepts. Writes to docs/onboarding.md.
/onboardIndexes this folder and saves a persistent overview that future sessions pick up automatically. In a git repo this writes `codebase:onboard` (code-shape map). In a non-git folder this writes `project:onboard` (file-shape index built by deterministic extractors — no LLM at index time).
/onboardGenerates a comprehensive developer onboarding guide including architecture diagram, tech stack, setup instructions, key files, API routes, database schema, and common gotchas.
/onboardGuides new Swarm users through core concepts—outcomes, modes—and launches their first team via interactive step-by-step gates.
/onboardScans new codebase, checks context and files, classifies stack, maps architecture, sets up rules, and saves knowledge to .memory/ for building.