| name | byterover-onboard |
| description | Interactive knowledge-driven project onboarding. Queries comprehensive knowledge across all domains, presents a structured project overview, identifies knowledge gaps, and suggests running explore to fill them. |
ByteRover Project Onboarding
A structured workflow for getting up to speed on a project using ByteRover's accumulated knowledge. Presents a comprehensive overview and identifies areas needing further exploration.
When to Use
- Starting work on an unfamiliar project
- When a new team member needs to get up to speed quickly
- When returning to a project after a long break
- When you need a quick overview of project state and conventions
Prerequisites
Run brv status first. If errors occur, instruct the user to resolve them in the brv terminal. See the byterover skill's TROUBLESHOOTING.md for details.
The project should ideally have existing knowledge from a prior byterover-explore run. If the knowledge base is empty, recommend running byterover-explore first for best results.
Process
Phase 1: Comprehensive Knowledge Retrieval
Query every major knowledge domain to build a complete picture:
brv query "What is the technology stack — languages, frameworks, and key dependencies?"
brv query "What is the architecture — directory structure, layers, data flow, and entry points?"
brv query "What coding conventions and patterns are used — naming, imports, error handling?"
brv query "What testing approach is used — framework, patterns, organization?"
brv query "What external integrations exist — APIs, databases, auth providers, services?"
brv query "What concerns exist — tech debt, known issues, fragile areas, security risks?"
Save the responses for synthesis in Phase 3.
Phase 2: Assess Knowledge Completeness
For each domain, rate coverage:
| Domain | Rating | Criteria |
|---|
| Technology Stack | Comprehensive / Partial / Missing | Lists specific deps, versions, runtime |
| Architecture | Comprehensive / Partial / Missing | Describes layers, data flow, entry points |
| Conventions | Comprehensive / Partial / Missing | Specifies naming, imports, error handling |
| Testing | Comprehensive / Partial / Missing | Names framework, patterns, organization |
| Integrations | Comprehensive / Partial / Missing | Lists specific services, configs |
| Concerns | Comprehensive / Partial / Missing | References specific files, issues |
- Comprehensive — Detailed, specific, references file paths
- Partial — Some knowledge exists but lacks specificity or is incomplete
- Missing — No knowledge returned or only vague generalities
Phase 3: Present Structured Overview
Synthesize retrieved knowledge into a structured onboarding guide:
Project Summary
- What the project does (purpose and scope)
- Technology stack (languages, runtime, key frameworks)
- Key dependencies and their roles
Architecture
- Directory structure and what lives where
- Architectural layers and their responsibilities
- Data flow (how requests/data move through the system)
- Entry points (where execution begins)
Development Guide
- Coding conventions (naming, imports, code style)
- Common patterns to follow (with examples from knowledge base)
- Error handling approach
- How to add new features (where to put code, what patterns to use)
Testing
- Test framework and runner
- Where tests live and naming conventions
- How to write tests (mocking, fixtures, assertions)
- How to run tests
Key Concerns
- Known tech debt and its location
- Fragile areas to be careful with
- Known issues and workarounds
- Security considerations
Getting Started
- How to set up the development environment
- How to run the project locally
- How to run tests
- Key configuration files
Present each section only if knowledge exists for it. Skip sections where the knowledge base returned nothing — don't fabricate information.
Phase 4: Identify Gaps and Suggest Next Steps
For domains rated as Partial or Missing:
Knowledge gaps found:
- [Domain]: [What's missing]
→ Run byterover-explore to map this area
→ Or curate manually: brv curate "[domain]: [description]" -f [files]
If the user has specific questions about the project:
- Query the knowledge base for an answer
- If the answer is comprehensive, present it
- If the answer is incomplete, note the gap and suggest exploring that area
Phase 5: Curate Onboarding Notes
If the onboarding process reveals new insights — for example, the user asks a question that leads to reading code and discovering undocumented behavior:
brv curate "[domain]: [new insight discovered during onboarding]" -f [relevant files]
This builds the knowledge base for future onboarding sessions.
Completion
Present the full onboarding summary to the user:
- Overview completeness — How much of the project is documented (X/6 domains covered)
- Key takeaways — The most important things to know before starting work
- Gaps found — What's missing and how to fill it
- Suggested next steps:
- Run
byterover-explore for missing domains
- Start with a specific area based on the user's goals
- Review specific files for hands-on understanding
Important Rules
- Never read secrets — Skip
.env, credential files, and similar
- Knowledge-only — Present what's in the knowledge base; do not fabricate information
- Be honest about gaps — If a domain has no knowledge, say so and suggest explore
- Practical first — Prioritize "how to run/test/deploy" over theoretical architecture
- Structured presentation — Use clear sections and tables for scanability
- Suggest explore, not manual investigation — When gaps exist, recommend
byterover-explore rather than asking the agent to manually explore
- Curate discoveries — If new insights emerge during onboarding, store them
- Max 5 files per curate — Break down large curate operations if needed
- Verify curations — After storing critical context, run
brv curate view <logId> to confirm what was stored (logId is printed by brv curate on completion). Run brv curate view --help to see all options.
