Load PROACTIVELY when starting work on an unfamiliar codebase or setting up a new project. Use when user says "help me understand this codebase", "onboard me", "what does this project do", "set up my environment", or "map the architecture". Covers codebase structure analysis, architecture mapping, dependency auditing, convention and pattern detection, developer environment setup, and documentation of findings for rapid productive contribution.
Analyzes unfamiliar codebases to map architecture, detect patterns, and generate setup documentation for rapid developer onboarding.
/plugin marketplace add mgd34msu/goodvibes-plugin/plugin install goodvibes@goodvibes-marketThis skill inherits all available tools. When active, it can use any tool Claude has access to.
references/onboarding-patterns.mdscripts/validate-onboarding.shscripts/
validate-onboarding.sh
references/
onboarding-patterns.md
This skill teaches you how to systematically onboard onto new projects using GoodVibes precision tools. A thorough onboarding process maps the architecture, identifies patterns, validates the environment, and generates documentation for rapid productive contribution.
Load this skill when:
Trigger phrases: "onboard to this project", "understand this codebase", "setup dev environment", "map the architecture", "generate project docs".
Understand the directory layout, monorepo configuration, and entry points.
Use discover to map the project's directory layout and identify key configuration files.
discover:
queries:
- id: config_files
type: glob
patterns:
- "package.json"
- "tsconfig*.json"
- "*.config.{js,ts,mjs,cjs}"
- ".env*"
- "docker-compose*.yml"
- "Dockerfile*"
- id: src_structure
type: glob
patterns:
- "src/**/*"
- "app/**/*"
- "pages/**/*"
- "lib/**/*"
- id: monorepo_indicators
type: glob
patterns:
- "pnpm-workspace.yaml"
- "lerna.json"
- "nx.json"
- "turbo.json"
- "packages/*/package.json"
- "apps/*/package.json"
verbosity: files_only
What this reveals:
Find main application entry points, server files, and public APIs.
discover:
queries:
- id: entry_points
type: glob
patterns:
- "src/index.{ts,tsx,js,jsx}"
- "src/main.{ts,tsx,js,jsx}"
- "src/app.{ts,tsx,js,jsx}"
- "app/layout.{ts,tsx,js,jsx}"
- "pages/_app.{ts,tsx,js,jsx}"
- "server.{ts,js}"
- id: api_routes
type: glob
patterns:
- "src/api/**/*"
- "app/api/**/*"
- "pages/api/**/*"
- "routes/**/*"
- id: public_assets
type: glob
patterns:
- "public/**/*"
- "static/**/*"
verbosity: files_only
What this reveals:
Use precision_read to examine package.json and key config files.
precision_read:
files:
- path: "package.json"
extract: content
- path: "tsconfig.json"
extract: content
verbosity: standard
What this reveals:
Analyze dependencies for version currency, security vulnerabilities, and bundle size.
Extract dependencies from package.json files.
precision_grep:
queries:
- id: dependencies
pattern: '"dependencies":\s*\{[\s\S]*?\}'
glob: "**/package.json"
multiline: true
- id: dev_dependencies
pattern: '"devDependencies":\s*\{[\s\S]*?\}'
glob: "**/package.json"
multiline: true
- id: peer_dependencies
pattern: '"peerDependencies":\s*\{[\s\S]*?\}'
glob: "**/package.json"
multiline: true
output:
format: matches
verbosity: standard
Run npm/yarn/pnpm commands to check for updates.
precision_exec:
commands:
- cmd: "npm outdated --json"
- cmd: "npm audit --json"
verbosity: standard
What this reveals:
Identify large dependencies and potential optimizations.
precision_exec:
commands:
- cmd: "npx bundle-phobia-cli --json react react-dom next"
verbosity: minimal
What this reveals:
Map module boundaries, data flow, and API surface.
Use precision_read with outline extraction to map the codebase structure.
# Note: path "src" works as a directory - precision_read will recursively extract outline
precision_read:
files:
- path: "src"
extract: outline
output:
max_per_item: 100
verbosity: standard
What this reveals:
Use precision_read with symbol extraction to find exported functions, classes, and types.
# First discover the files
discover:
queries:
- id: lib_files
type: glob
patterns: ["src/lib/**/*.{ts,tsx}"]
- id: api_files
type: glob
patterns: ["src/api/**/*.{ts,tsx}"]
verbosity: files_only
# Then read symbols from discovered files
precision_read:
files:
# Use file paths from discover results
- path: "src/lib/index.ts" # Example - use actual discovered paths
extract: symbols
- path: "src/api/index.ts" # Example - use actual discovered paths
extract: symbols
symbol_filter: ["function", "class", "interface", "type"]
verbosity: minimal
What this reveals:
Trace imports and exports to understand module dependencies.
discover:
queries:
- id: imports
type: grep
pattern: '^import .* from ["''].*["''];?$'
glob: "src/**/*.{ts,tsx,js,jsx}"
- id: exports
type: grep
pattern: '^export (default|const|function|class|interface|type|enum)'
glob: "src/**/*.{ts,tsx,js,jsx}"
verbosity: count_only
What this reveals:
Identify code style, naming patterns, and file organization rules.
Search for naming patterns in files and symbols.
discover:
queries:
- id: component_naming
type: grep
pattern: 'export (default )?(function|const) [A-Z][a-zA-Z]*'
glob: "src/components/**/*.{ts,tsx}"
- id: hook_naming
type: grep
pattern: 'export (default )?(function|const) use[A-Z][a-zA-Z]*'
glob: "src/**/*.{ts,tsx}"
- id: util_naming
type: grep
pattern: 'export (default )?(function|const) [a-z][a-zA-Z]*'
glob: "src/lib/**/*.{ts,tsx}"
verbosity: count_only
What this reveals:
use prefix for hooksAnalyze directory structure for organizational conventions.
discover:
queries:
- id: index_files
type: glob
patterns: ["**/index.{ts,tsx,js,jsx}"]
- id: type_files
type: glob
patterns: ["**/*.types.{ts,tsx}", "**/types.{ts,tsx}", "**/types/**/*"]
- id: test_colocation
type: glob
patterns:
- "**/*.test.{ts,tsx}"
- "**/__tests__/**/*"
verbosity: count_only
What this reveals:
Find ESLint, Prettier, and other code quality configurations.
discover:
queries:
- id: lint_config
type: glob
patterns:
- ".eslintrc*"
- "eslint.config.{js,mjs,cjs}"
- ".prettierrc*"
- "prettier.config.{js,mjs,cjs}"
- id: editor_config
type: glob
patterns:
- ".editorconfig"
- ".vscode/settings.json"
verbosity: files_only
Read the configs:
precision_read:
files:
- path: ".eslintrc.json"
extract: content
- path: ".prettierrc"
extract: content
verbosity: standard
What this reveals:
Set up developer environment with required dependencies, config files, and database.
Read .nvmrc, package.json engines, or .node-version.
precision_grep:
queries:
- id: node_version_nvmrc
pattern: '.*'
glob: ".nvmrc"
- id: node_version_package
pattern: '"engines":\s*\{[\s\S]*?"node":\s*"[^"]+"'
glob: "package.json"
multiline: true
output:
format: matches
verbosity: standard
What this reveals:
Run the package manager install command.
precision_exec:
commands:
- cmd: "npm install"
timeout_ms: 300000
verbosity: minimal
For pnpm or yarn:
precision_exec:
commands:
- cmd: "pnpm install"
timeout_ms: 300000
verbosity: minimal
Identify required environment variables from .env.example or code.
precision_read:
files:
- path: ".env.example"
extract: content
verbosity: standard
Search for env var usage in code:
precision_grep:
queries:
- id: env_usage
pattern: 'process\.env\.[A-Z_]+'
glob: "src/**/*.{ts,tsx,js,jsx}"
output:
format: matches
max_per_item: 20
verbosity: minimal
What this reveals:
Check for database schema files, migrations, and seed scripts.
discover:
queries:
- id: prisma_schema
type: glob
patterns: ["prisma/schema.prisma"]
- id: migrations
type: glob
patterns:
- "prisma/migrations/**/*"
- "migrations/**/*"
- "db/migrations/**/*"
- id: seed_scripts
type: glob
patterns:
- "prisma/seed.{ts,js}"
- "db/seed.{ts,js}"
- "scripts/seed.{ts,js}"
verbosity: files_only
Run database setup:
precision_exec:
commands:
- cmd: "npx prisma generate"
- cmd: "npx prisma migrate dev"
- cmd: "npx prisma db seed"
verbosity: standard
What this reveals:
Understand build commands, dev server, hot reload, and test runners.
Extract scripts from package.json.
precision_grep:
queries:
- id: scripts
pattern: '"scripts":\s*\{[\s\S]*?\}'
glob: "package.json"
multiline: true
output:
format: matches
verbosity: standard
What this reveals:
dev or start command for local developmentbuild command for production buildtest command for running testslint command for lintingRun the build command to verify setup.
precision_exec:
commands:
- cmd: "npm run build"
timeout_ms: 300000
verbosity: standard
What this reveals:
Run the dev command to verify hot reload works.
precision_exec:
commands:
- cmd: "npm run dev"
timeout_ms: 60000
until:
pattern: "(ready|compiled|listening|started)"
kill_after: true # Stops dev server after pattern matches
verbosity: standard
What this reveals:
Execute test suite to verify test setup.
precision_exec:
commands:
- cmd: "npm test"
timeout_ms: 120000
verbosity: standard
What this reveals:
Identify recurring patterns for state management, error handling, authentication, and routing.
Search for state management libraries and patterns.
discover:
queries:
- id: react_state
type: grep
pattern: '(useState|useReducer|useContext)'
glob: "src/**/*.{ts,tsx}"
- id: zustand
type: grep
pattern: "(create|useStore).*from ['\"]zustand"
glob: "src/**/*.{ts,tsx}"
- id: redux
type: grep
pattern: "(useSelector|useDispatch|createSlice)"
glob: "src/**/*.{ts,tsx}"
- id: jotai
type: grep
pattern: "(atom|useAtom).*from ['\"]jotai"
glob: "src/**/*.{ts,tsx}"
verbosity: count_only
What this reveals:
Find error boundaries, try-catch patterns, and error reporting.
# Use precision_grep instead of discover for multiline patterns
precision_grep:
queries:
- id: error_boundaries
pattern: "(class|extends) .*ErrorBoundary"
glob: "src/**/*.{ts,tsx}"
- id: try_catch
pattern: "try \{[\s\S]*?\} catch"
glob: "src/**/*.{ts,tsx,js,jsx}"
multiline: true
- id: error_reporting
pattern: "(Sentry|Bugsnag|ErrorBoundary|reportError)"
glob: "src/**/*.{ts,tsx,js,jsx}"
output:
format: count_only
verbosity: minimal
What this reveals:
Identify authentication library and patterns.
discover:
queries:
- id: auth_providers
type: grep
pattern: "(NextAuth|Clerk|Auth0|Supabase|Lucia|useAuth)"
glob: "src/**/*.{ts,tsx}"
- id: protected_routes
type: grep
pattern: "(withAuth|requireAuth|ProtectedRoute|middleware)"
glob: "src/**/*.{ts,tsx}"
- id: session_usage
type: grep
pattern: "(getSession|useSession|getServerSession)"
glob: "src/**/*.{ts,tsx}"
verbosity: count_only
What this reveals:
Understand routing architecture.
discover:
queries:
- id: app_router
type: glob
patterns: ["app/**/page.{ts,tsx}", "app/**/layout.{ts,tsx}"]
- id: pages_router
type: glob
patterns: ["pages/**/*.{ts,tsx}"]
- id: react_router
type: grep
pattern: "(BrowserRouter|Routes|Route|useNavigate)"
glob: "src/**/*.{ts,tsx}"
verbosity: count_only
What this reveals:
Generate CLAUDE.md, architecture docs, and onboarding guides.
Write a comprehensive CLAUDE.md with project context.
precision_write:
files:
- path: ".claude/CLAUDE.md"
mode: fail_if_exists
content: |
# Project Name
## Overview
[Brief description of the project, its purpose, and key features]
## Architecture
- **Framework**: [Next.js 14 App Router / Remix / etc.]
- **Language**: [TypeScript]
- **Database**: [PostgreSQL with Prisma]
- **Authentication**: [Clerk / NextAuth]
- **State Management**: [Zustand / Redux / etc.]
## Directory Structure
```
src/
app/ # Next.js App Router pages and layouts
components/ # React components
lib/ # Utility functions and shared logic
api/ # API route handlers
types/ # TypeScript type definitions
```
## Development Workflow
1. Install dependencies: `pnpm install`
2. Setup environment: Copy `.env.example` to `.env.local`
3. Setup database: `npx prisma migrate dev`
4. Start dev server: `pnpm dev`
5. Run tests: `pnpm test`
## Key Patterns
- Components use PascalCase naming
- Utilities use camelCase naming
- Hooks start with `use` prefix
- Server components by default, use 'use client' directive for client components
## Testing
- Unit tests: Vitest
- E2E tests: Playwright
- Run with: `pnpm test`
## Deployment
- Platform: [Vercel / Netlify / etc.]
- CI/CD: [GitHub Actions]
- Deploy command: `pnpm build`
verbosity: minimal
Create a mermaid diagram of the architecture.
precision_write:
files:
- path: "docs/ARCHITECTURE.md"
mode: fail_if_exists
content: |
# Architecture
## System Overview
```mermaid
graph TD
A[Client Browser] --> B[Next.js App Router]
B --> C[React Server Components]
B --> D[API Routes]
D --> E[Database - Prisma]
D --> F[External APIs]
C --> E
```
## Module Boundaries
- `app/`: Page routes and layouts (Next.js App Router)
- `components/`: Reusable UI components
- `lib/`: Business logic and utilities
- `api/`: Backend API handlers
## Data Flow
1. User requests page -> Next.js App Router
2. Server Component fetches data -> Prisma -> Database
3. Server renders component with data
4. Client receives HTML with hydration instructions
5. Client-side interactions -> API routes -> Database
## External Dependencies
- Authentication: Clerk
- Email: Resend
- Storage: Vercel Blob
verbosity: minimal
Generate a checklist for new developers.
precision_write:
files:
- path: "docs/ONBOARDING.md"
mode: fail_if_exists
content: |
# Onboarding Checklist
## Prerequisites
- [ ] Node.js 18+ installed
- [ ] pnpm installed (`npm install -g pnpm`)
- [ ] Git configured
- [ ] PostgreSQL installed locally (or Docker)
## Setup Steps
1. [ ] Clone repository
2. [ ] Install dependencies: `pnpm install`
3. [ ] Copy `.env.example` to `.env.local`
4. [ ] Fill in environment variables (get from team)
5. [ ] Setup database: `npx prisma migrate dev`
6. [ ] Seed database: `npx prisma db seed`
7. [ ] Start dev server: `pnpm dev`
8. [ ] Open http://localhost:3000
9. [ ] Run tests: `pnpm test`
10. [ ] Verify build: `pnpm build`
## Key Resources
- Architecture: [docs/ARCHITECTURE.md](./ARCHITECTURE.md)
- API Docs: [docs/API.md](./API.md)
- Code Review: Use `/code-review` skill
## First Tasks
1. Read through CLAUDE.md for project context
2. Explore the codebase structure
3. Review recent pull requests
4. Pick a "good first issue" from GitHub
verbosity: minimal
Understand Git branching strategy, PR process, and CI/CD pipeline.
Find branch protection rules and workflow files.
discover:
queries:
- id: github_workflows
type: glob
patterns: [".github/workflows/**/*.yml", ".github/workflows/**/*.yaml"]
- id: git_hooks
type: glob
patterns: [".husky/**/*", ".git/hooks/**/*"]
- id: branch_config
type: glob
patterns: [".github/CODEOWNERS", ".github/pull_request_template.md"]
verbosity: files_only
Read GitHub Actions workflows:
precision_read:
files:
- path: ".github/workflows/ci.yml"
extract: content
verbosity: standard
What this reveals:
Read PR template and contributing guidelines.
precision_read:
files:
- path: ".github/pull_request_template.md"
extract: content
- path: "CONTRIBUTING.md"
extract: content
verbosity: standard
What this reveals:
Search for commit message conventions.
# Check for commitlint config
precision_grep:
queries:
- id: commitlint
pattern: '.*'
glob: ".commitlintrc*"
output:
format: matches
verbosity: minimal
# Check commit convention from recent commits
precision_exec:
commands:
- cmd: "git log --oneline -20"
verbosity: standard
What this reveals:
Verify environment works end-to-end.
Execute all tests with coverage.
precision_exec:
commands:
- cmd: "npm test -- --coverage"
timeout_ms: 180000
verbosity: standard
What this reveals:
Run linting to ensure code quality.
precision_exec:
commands:
- cmd: "npm run lint"
verbosity: standard
What this reveals:
Run TypeScript type checker.
precision_exec:
commands:
- cmd: "npm run typecheck"
verbosity: standard
What this reveals:
any usageBuild for production and check bundle size.
precision_exec:
commands:
- cmd: "npm run build"
timeout_ms: 300000
- cmd: "ls -lh .next/static/chunks" # Next.js example
verbosity: standard
What this reveals:
Don't try to understand everything at once. Start with:
Then dive deeper into architecture, patterns, and contribution workflow.
discover with verbosity: count_only first to gauge scopeverbosity: files_only to build target listsprecision_read with extract: outline before reading full contentprecision_grep with output.format: count_only for pattern prevalence checksCreate or update documentation during onboarding:
Run builds, tests, and linting early in the onboarding process. This catches environment issues before you invest time in understanding the codebase.
When you find:
Document them as questions for the team.
Problem: Jumping into code reading without installing dependencies.
Solution: Always run npm install first. Many tools (TypeScript, ESLint) need dependencies to function.
Problem: Missing .env.local file causes runtime errors.
Solution: Copy .env.example to .env.local and fill in required values. Ask team for secrets.
Problem: Assuming the build works without verifying.
Solution: Run npm run build early to catch configuration issues, missing dependencies, or TypeScript errors.
Problem: Application fails at runtime due to missing database schema.
Solution: Run migrations (npx prisma migrate dev) and seed data before starting dev server.
Problem: Missing key context in README.md, CONTRIBUTING.md, or project docs.
Solution: Use precision_read to read all markdown files in the root and docs/ folder first.
Use the validation script to check your onboarding completeness:
bash plugins/goodvibes/skills/quality/project-onboarding/scripts/validate-onboarding.sh
This will verify:
For detailed patterns and examples, see:
quality/code-review - Review code quality after understanding the codebasearchitecture/system-design - Design new features following existing patternstesting/test-strategy - Write tests matching project conventionsActivates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.