# Handoff For Future Maintainers

This handoff is for the next maintainer and their AI agent. Read it first when you receive this zip or continue work in this folder.

## One-Line Summary

This is a portable AI-agent onboarding/RAG kit for TTC recruiting interns: it guides learners one confirmed step at a time, answers questions from local indexed evidence, and gives maintainers strict rules for updating modules and sources without breaking the system.

## Project Handoff Summary

What this project does: it turns the TTC recruiting intern SOP into a portable AI-agent onboarding and local RAG kit. New interns can follow structured onboarding and recruiting-training steps, while maintainers can update modules, add sources, rebuild the search index, and repackage the kit under strict rules.

What has been built:

- A structured onboarding kit with 10 enabled modules covering offer/preboarding, Day 1 landing, intern role basics, training acceptance, recruiting intern hiring, sourcing channels, candidate activation, interview arrangement, PPL management, and offboarding.
- Three journeys in `kit.yaml`: Day 1 new hire, recruiting intern training, and lifecycle closeout.
- A Codex skill entrypoint at `skills/onboarding-buddy/SKILL.md`, plus `start.prompt.md` for direct learner startup.
- A strict maintainer contract in `MAINTAINERS.md` covering CRUD, read scope, source handling, state handling, index generation, verification, and packaging rules.
- A six-layer `.ai/context/` map for intent, rules, workspace, state ledger, eval checklists, and systemization backlog.
- Cross-agent adapter files for Claude Code, Gemini, GitHub Copilot, Cursor, and Cline, all kept thin and pointed back to shared contracts.
- Deterministic scripts for validation, source ingestion, indexing, local search, bootstrap generation, optional uv environment bootstrap, skill installation, and module CRUD.
- A manifest-backed source corpus under `sources/` and `assets/`, with generated full-text search under `search/`.
- A first-run package bootstrap flow through `BOOTSTRAP.md` and `scripts/bootstrap_session.py`.

Recent maintenance work:

- `实习生学习专区 - 决胜` was manually supplied, sanitized, and moved from failed/metadata-only to ingested source text.
- The full `实习生PPL` bitable body was confirmed unnecessary for the current kit; it remains metadata-only by design, not as an active gap.
- `sourcing-channels` was updated through version `0.1.5` with corrected account/channel rules.
- Liepin and Maimai accounts are registered by interns using their own phone/identity information as required by the platforms, while company JD publishing must use team-confirmed company information.
- Boss account rules now say: prioritize registering with the intern's own Boss account; the Celine account can only be used by one person and is a fallback; when registering a personal Boss account, choose the role `猎头`, not `招聘者`; if enterprise verification is required, choose `同事协助认证`.
- Boss, Liepin, and Maimai source notes and FAQs were sanitized so the kit stores workflow rules and company/JD fields, not phone numbers, ID numbers, verification codes, QR codes, face verification materials, colleague avatars, passwords, or raw signed Feishu asset URLs.
- `v0.1.1` maintenance fixed package portability, search path portability, validator coverage, CSV privacy scanning, centralized sensitive-pattern handling, help_ref anchor checks, lean index metadata, validator warnings, installed skill location notes, and release packaging rules.
- `v0.1.2` maintenance added Python-unavailable Q&A fallback guidance to bootstrap, learner startup, and the Codex skill entrypoint.
- `v0.1.3` maintenance added the post-homework leader interview scheduling flow to `interview-arrangement`: create a Feishu calendar event, invite candidate/interviewers/organizer, reserve room or video meeting, add sanitized `OpenAI分析`/candidate summary, attach permitted resume/homework materials, confirm attendance status, sync the candidate, and update PPL.
- `v0.1.4` maintenance retained two processed reference screenshots for the same flow under `assets/images/`, with matching `sources/image-notes/` descriptions. The raw screenshots remain excluded because they contain candidate and employee identifiers.
- `v0.1.5` maintenance added optional uv bootstrap scripts and updated startup rules so agents try to establish Python/uv before Q&A; direct `search/chunks.jsonl` reading is now an emergency fallback only when installation is declined or blocked.
- `v0.1.6` maintenance added the OpenAI company research homework prompt to `candidate-activation` and added a visual-trust rule: when relevant official or redacted images exist, pair them with concise text; never send raw sensitive screenshots.
- `v0.1.7` maintenance wired the post-homework meeting-room/leader-interview Q&A directly to the two redacted Feishu Calendar screenshots, and clarified that agents should render local images with absolute Markdown paths when the chat environment supports it.

Current snapshot:

- Enabled modules: 10.
- Source manifest items: 29.
- Manual source notes: 5.
- Search index: 510 chunks after the latest v0.1.7 refresh.
- Known remaining source gap: `实习生清单` is still metadata-only because it is a Sheet unsupported by `docs +fetch`; ingest it only if sheet-backed answers become required.

## Design Philosophy

The kit is designed around six-layer vertical context and progressive disclosure.

Six-layer model:

1. Surface: the immediate learner or maintainer request.
2. Context: stable rules, role assumptions, safety boundaries, and read order.
3. Workspace: real files, modules, sources, scripts, assets, search index, and tools.
4. State: current progress, locked decisions, known blockers, verification evidence, and next actions.
5. Intent: the business and learning outcome, not just the visible prompt.
6. System: reusable scripts, skill, checklists, templates, and future productization backlog.

Progressive disclosure rules:

- Do not load everything by default.
- For learner guidance, read only the current journey, module, and step context.
- For Q&A, search first, then open only cited files.
- For sources, trust manifest-backed extracted text, not raw binary assets.
- For maintenance, read the rules and only the affected module/source files.
- For architecture or resume work, use `.ai/context/`.

## Current Architecture

```text
AGENTS.md                         Highest local operating contract
AGENT_COMPATIBILITY.md            Cross-agent compatibility map
BOOTSTRAP.md                      First-run package bootstrap prompt
CLAUDE.md                         Claude Code adapter
GEMINI.md                         Gemini adapter
HANDOFF.md                        This maintainer handoff
MAINTAINERS.md                    CRUD, read-scope, verification, packaging rules
.github/copilot-instructions.md   GitHub Copilot adapter
.cursor/rules/onboarding-kit.mdc  Cursor adapter
.clinerules                       Cline adapter
.ai/context/                      Six-layer durable context and state
kit.yaml                          Kit metadata, journeys, owners, search paths
start.prompt.md                   Learner startup prompt and initialization script
install.md                        Direct-use and skill-install instructions
skills/onboarding-buddy/SKILL.md  Codex skill entrypoint
modules/<module-id>/              Pluggable onboarding modules
sources/                          Source evidence and extracted searchable text
assets/                           Downloaded binary originals
search/                           Generated full-text index
state-template/                   Learner runtime state schema
scripts/                          Validation, ingestion, indexing, search, install, CRUD tools
```

## How To Start As A Maintainer

1. Read `AGENTS.md`.
2. Read this `HANDOFF.md`.
3. Read `MAINTAINERS.md`.
4. If the task is architectural, read `.ai/context/README.md` and the smallest relevant context file.
5. For module work, inspect affected modules with `python3 scripts/module_crud.py show <module-id>`.
6. For source work, inspect `sources/README.md` and `sources/source-manifest.yaml`.

Python command compatibility: scripts require Python 3.10+. Examples use `python3` for macOS/Linux; on Windows, if `python3` is unavailable, use `python` or `py -3` with the same arguments. If Python is unavailable, agents should ask before running `bootstrap.ps1` or `sh bootstrap.sh` to install uv and use uv-managed Python. Direct `search/chunks.jsonl` reading is only the emergency Q&A fallback when setup is declined or blocked.

Quick health check:

```bash
python3 scripts/validate_kit.py
python3 scripts/index_knowledge.py
python3 scripts/search_knowledge.py "这个项目做了什么 handoff" --top-k 3
```

## How To Start A New Agent Session With Full Package Context

Use this when handing the zip to a new Codex, Claude Code, Cursor, GitHub Copilot, Gemini, Cline, or compatible agent session and you want a one-time package warmup before normal Q&A:

1. Unzip the package and open the `onboarding-kit/` folder.
2. Send the first-message prompt from `BOOTSTRAP.md`.
3. The agent should detect Python first. If Python 3.10+ is unavailable, it should ask before using `bootstrap.ps1` or `sh bootstrap.sh` to install uv and run with uv-managed Python.
4. The agent should validate, rebuild the index, run `scripts/bootstrap_session.py`, read `.ai/context/session-bootstrap.md`, and search-test one representative question.
5. For later questions in the same agent session, the agent should use `scripts/search_knowledge.py`, `sources/source-manifest.yaml`, and cited files instead of rescanning the full package.

## How To Start As A Learner

Open the kit folder in Codex and send the startup prompt from `start.prompt.md`.

The agent should:

1. Read `AGENTS.md`.
2. Read `skills/onboarding-buddy/SKILL.md`.
3. Read `kit.yaml`.
4. Ask for name, role, onboarding date, mentor, and journey if no learner state exists.
5. Present exactly one step.
6. Wait for completion evidence or confirmation.
7. Update state before showing the next step.

## Core Execution Workflows

### Answer A Question

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

Rules:

- Open only the cited files needed to answer.
- Check `sources/source-manifest.yaml` before citing source corpus files.
- Cite module/source path and heading.
- If unsupported, say unresolved and route to the owner.

### Add A Module

```bash
python3 scripts/module_crud.py create <module-id> --title "<title>" --owner "<owner>"
```

Then update the module's four files:

- `module.yaml`
- `steps.yaml`
- `knowledge.md`
- `faq.yaml`

Run validation, indexing, and representative search after the change.

### Update A Module

1. Read only the affected module's four files.
2. Edit only `module.yaml`, `steps.yaml`, `knowledge.md`, and `faq.yaml`.
3. Bump `module.yaml.version` and `last_reviewed` for substantive changes.
4. Validate, index, and search-test.

### Disable A Module

```bash
python3 scripts/module_crud.py disable <module-id>
```

Then remove it from active journeys in `kit.yaml` if needed. Do not delete modules by default.

### Add Or Refresh Sources

For primary Feishu/Lark source changes:

```bash
python3 scripts/ingest_lark_sources.py
python3 scripts/validate_kit.py
python3 scripts/index_knowledge.py
```

For manual non-Lark sources:

1. Put binary originals under `assets/pdf/`, `assets/images/`, or `assets/video/`.
2. Put searchable extracted text under `sources/pdf-text/`, `sources/image-notes/`, `sources/tables/`, or `sources/external-links/`.
3. Update `sources/source-manifest.yaml`.
4. Validate, index, and search-test.

### Package The Kit

Run this from the kit root:

```bash
python3 scripts/package_kit.py
```

Only `scripts/package_kit.py` may create release zips. Do not use PowerShell `Compress-Archive`, Finder compression, or manual zip tools. The zip filename must match `kit.yaml` version and must not contain `state/` or learner runtime data.

## Current Development State

Status:

- Kit is functional and packaged at `v0.1.7`.
- 10 modules are enabled.
- Source corpus is manifest-backed with 29 source items.
- Full-text search is rebuilt; the latest v0.1.7 refresh produced 510 chunks.
- Codex skill exists and has an install script that appends the kit location to installed copies.
- Six-layer `.ai/context/` scaffold is populated and indexed.
- Cross-agent adapter files are present for Claude Code, Gemini, GitHub Copilot, Cursor, and Cline.
- `sourcing-channels` is currently at version `0.1.5`.
- `candidate-activation` is currently at version `0.1.1`.
- `interview-arrangement` is currently at version `0.1.2`.

Current source corpus:

- 29 manifest items.
- 6 linked document references.
- 1 embedded sheet.
- 2 media resources.
- 9 images.
- 4 external links.
- 5 sanitized manual notes.
- 1 PDF downloaded and text-extracted.
- 1 video downloaded with metadata only.

Known partial or intentionally metadata-only sources:

- `实习生PPL`: metadata-only by maintainer decision; the full bitable body is not needed for the current kit unless future work requires a sanitized table export.
- `实习生清单`: metadata-only because it is a Sheet unsupported by `docs +fetch`.

## Safety Rules

- Never store real passwords, verification codes, private keys, tokens, full identity documents, bank card numbers, or raw signed Feishu asset URLs.
- Do not store phone numbers, ID numbers, face verification materials, authentication QR codes, colleague avatars, or personal account authentication details in searchable text.
- Do not cite binary PDFs/images/videos unless extracted text or image/video notes exist under `sources/`.
- Do not hand-edit generated search files.
- Do not delete modules by default.
- Do not answer from memory when indexed local evidence exists.

## Current Next Best Improvements

1. Add Sheet-specific ingestion for `实习生清单` if sheet-backed answers become required.
2. Add optional transcription for the downloaded onboarding video.
3. Add regression Q&A evals for Day 1, channels, PPL, offer/onboarding, and offboarding.
4. Add manual source item templates under `.ai/context/templates/`.
5. Add a reusable release/handoff template if this zip-based kit pattern repeats.

## If You Are Unsure

Use this order:

1. `AGENTS.md` for behavior.
2. `HANDOFF.md` for orientation.
3. `MAINTAINERS.md` for maintenance rules.
4. `.ai/context/README.md` for deep context.
5. `scripts/search_knowledge.py` for evidence.
6. `sources/source-manifest.yaml` for source truth.
