onboarding

Onboarding

Generate a comprehensive developer onboarding guide for an unfamiliar codebase and write it to docs/ONBOARDING.md.

Instructions

1. Use Read on README.md, then attempt to read whichever of the following exist: package.json, pyproject.toml, go.mod, CLAUDE.md, docs/assumptions.md.

2. Use Glob to map the top-level directory structure (*). For each top-level folder found, describe its purpose based on its name and contents (e.g., src/ → application source, scripts/ → automation scripts, docs/ → project documentation).

3. Use Glob to find entry points matching: index.*, main.*, server.*, app.*, cmd/**/*. Read the primary entry point to understand how the application starts.

4. Use Read on any Makefile, package.json (scripts section), or Taskfile.yml to identify key commands: install, run, test, build, lint.

5. Use Glob to find .env.example or any env var documentation files. List all required environment variables with their descriptions.

   SECURITY: Read .env.example only — never read .env or any file containing real credential values, and never include actual secret values in the generated guide. Document variable names and descriptions only.

6. Use Bash to count files by detected language type. Adapt the command to the language detected:

   • TypeScript/JavaScript: find . -name "*.ts" -o -name "*.js" | grep -v node_modules | wc -l
   • Python: find . -name "*.py" | grep -v __pycache__ | wc -l
   • Go: find . -name "*.go" | wc -l

7. Generate architecture diagram.

   a. Use Read on the primary entry point file identified in step 3 to understand how the application initializes and what it connects to.

   b. Use Glob to find configuration files that reveal infrastructure: docker-compose.yml, *.env.example, infrastructure/**, terraform/**, serverless.yml, .github/workflows/**.

   c. Use Grep to identify major inter-module dependencies: import/require/use statements at the top of the entry point and primary route/handler files.