---
name: onboarding-buddy
description: Use when a learner or maintainer needs structured newcomer onboarding, Day 1 landing guidance, recruiting intern training, step-by-step confirmation, onboarding state tracking, FAQ answering, or searchable RAG-style answers from this Onboarding Agent Kit.
---

# Onboarding Buddy

## Required Read Order

1. Read `AGENTS.md`.
2. Read `kit.yaml`.
3. For maintainer requests, read `MAINTAINERS.md`.
4. Read the learner's state file if present.
5. Read the selected module's `module.yaml` and `steps.yaml`.
6. Read `knowledge.md` and `faq.yaml` only when needed for the current step or question.
7. For source-grounded answers, consult `sources/source-manifest.yaml` before trusting any source file.

## First-Run Package Bootstrap

When the user asks for "首次包接手", "完整读取压缩包", "bootstrap", or asks to prepare the package so later questions do not reread everything:

1. Read `BOOTSTRAP.md`.
2. Run `python3 scripts/validate_kit.py`.
3. Run `python3 scripts/index_knowledge.py`.
4. Run `python3 scripts/bootstrap_session.py`.
5. Read `.ai/context/session-bootstrap.md`.
6. Run one representative search test.
7. In the same agent session, answer later questions with search-first retrieval instead of rescanning the full package.

Python fallback: scripts require Python 3.10+. On Windows, use `python` or `py -3` if `python3` is unavailable. If Python is not installed, ask the user before running `bootstrap.ps1` or `sh bootstrap.sh` to install uv and use uv-managed Python, including before ordinary Q&A. Read `search/chunks.jsonl`, `sources/source-manifest.yaml`, and cited files manually only as an emergency Q&A fallback when the user declines installation or setup is blocked. Do not perform maintenance, source ingestion, index rebuilds, or packaging without Python 3.10+ or user-approved uv bootstrap.

Stable environment fallback: if Python 3.10+ is unavailable for either Q&A or maintenance, ask the user before running `bootstrap.ps1` on Windows or `sh bootstrap.sh` on macOS/Linux. These scripts use uv to run a managed Python 3.12 when local Python is missing. Never install uv silently.

This bootstrap is session-scoped. A new agent conversation must run it again.

## Start Flow

When the user says "开始入职", "继续 onboarding", "启动新人引导", or similar:

1. If no state exists, ask for name, role, onboarding date, mentor, and journey.
2. Use `kit.yaml.default_journey` when the user does not choose a journey.
3. Find the first incomplete module and step in that journey.
4. Present exactly one step using the template in `AGENTS.md`.
5. Wait for completion confirmation, evidence, or a question.

## Step Completion

- Accept clear confirmations such as "完成", "做完了", "已完成".
- If a step requires evidence, ask for the required evidence before marking complete.
- Mark the step complete in state before presenting the next step.
- If the user reports a blocker, record the blocker and give the module's escalation path.

## Question Answering

For any question:

1. Search current module content first when a current module exists.
2. Search enabled modules next.
3. Search source corpus files listed in `sources/source-manifest.yaml` last.
4. Open only the cited result files needed to answer.
5. When a cited source has a relevant, manifest-backed image or flowchart, include or reference the official/redacted image alongside the text answer. If the interface supports local image display, resolve the asset path from the kit root and render it as a Markdown image with an absolute filesystem path; otherwise provide the relative asset path and a short description. Never send raw sensitive screenshots.
6. Answer with citations.
7. If no answer is found, say it is unresolved and route to owner.

Preferred command for local search:

```bash
python3 scripts/search_knowledge.py "<question>"
```

If Python is unavailable, ask to run the optional uv bootstrap before Q&A. If the user declines or setup is blocked, answer Q&A by opening `search/chunks.jsonl` and the relevant cited files manually; tell the user this is an emergency fallback and that Python 3.10+ or user-approved uv bootstrap is required for normal local search, validation, index rebuilds, source ingestion, and packaging.

If Python is unavailable, ask for permission to use the optional uv bootstrap first:

```bash
# Windows
powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1

# macOS/Linux
sh bootstrap.sh
```

## Maintainer Mode

When the user asks to add, update, disable, or inspect modules:

1. Follow `AGENTS.md` and `MAINTAINERS.md` maintenance rules.
2. Use `scripts/module_crud.py` for scaffolding when possible.
3. For source changes, follow `sources/README.md` and update `sources/source-manifest.yaml`.
4. Run `scripts/ingest_lark_sources.py` when the primary Feishu source changed or contains new nested assets.
5. Run `scripts/validate_kit.py`.
6. Run `scripts/index_knowledge.py`.
7. Report changed modules or sources, validation result, and index rebuild result.

## Skill Installation

Preferred local installer:

```bash
python3 scripts/install_skill.py
```

Dry-run check:

```bash
python3 scripts/install_skill.py --dry-run
```
