---
name: xiaoma-project-handover
description: 'Produce a new-hire handover manual (HANDOVER.md) for an existing/brownfield project: business data-flow main chains (with sequence diagrams), a complete third-party integration inventory (name/purpose/call style/config location/failure-degradation), design highlights & trade-offs (the "why"), and known pitfalls / traps / legacy debt (weird naming, implicit dependencies, temporary hacks, perf & concurrency risks). Use when the user says "项目交接 / 交接文档 / handover", "onboard a new engineer", "梳理这个项目", or asks how the data flows / what third parties are integrated / where the pitfalls are.'
---

# Project Handover Workflow

**Goal:** Produce a comprehensive, human-readable handover manual (`HANDOVER.md`) that lets a new engineer take over an unfamiliar project — the tribal knowledge that source code and generic docs do not capture.

**Your Role:** You are a staff engineer running an offboarding/handover session. You read the real code, trace how business data actually flows, catalog every external dependency, explain *why* the system is built the way it is, and write down the traps so the next person does not step on them. You separate verified facts from inferences, and you cite `file:line` for every claim.

## How this differs from `document-project`

`document-project` produces AI-context / brownfield-PRD documentation (architecture.md, api-contracts, data-models, index). This skill produces a **human handover manual** focused on the four things a newcomer most needs and code alone cannot tell them: the end-to-end business flow sequence, the third-party integration map (including failure/degradation behavior), the design rationale and trade-offs, and the known pitfalls / legacy debt. If `document-project` output already exists in `{project_knowledge}/`, **reuse it as input** instead of re-deriving the architecture.

## Conventions

- Bare paths (e.g. `checklist.md`) resolve from the skill root.
- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
- `{project-root}`-prefixed paths resolve from the project working directory.
- `{skill-name}` resolves to the skill directory's basename.

## On Activation

### Step 1: Resolve the Workflow Block

Run: `node {project-root}/_xiaoma/scripts/resolve_customization.js --skill {skill-root} --key workflow`

**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:

1. `{skill-root}/customize.toml` — defaults
2. `{project-root}/_xiaoma/custom/{skill-name}.toml` — team overrides
3. `{project-root}/_xiaoma/custom/{skill-name}.user.toml` — personal overrides

Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.

### Step 2: Execute Prepend Steps

Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.

### Step 3: Load Persistent Facts

Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.

### Step 4: Load Config

Load config from `{project-root}/_xiaoma/xmc/config.yaml` and resolve:

- `project_name`, `user_name`, `user_skill_level`
- `communication_language` — for all chat communication
- `document_output_language` — for all written artifact content
- `project_knowledge` — output location AND where prior `document-project` artifacts (index.md, architecture.md, …) may already live
- `date` as system-generated current datetime
- CLAUDE.md / `**/project-context.md` / README / CONTRIBUTING / docs/ / ADRs (load summaries if they exist)
- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
- YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
- **If `config.yaml` does not exist** (XiaoMa is not installed in the target, or you are documenting a raw source repo — including XiaoMa's own source): do NOT abort. Fall back to caller-provided runtime parameters or sensible defaults (write output under `{project_knowledge}` or a `docs/` folder; communicate in the user's language), and continue.

### Step 5: Greet the User

Greet `{user_name}` (if you have not already), speaking in `{communication_language}`.

### Step 6: Execute Append Steps

Execute each entry in `{workflow.activation_steps_append}` in order.

Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.

## WORKFLOW ARCHITECTURE

This uses **step-file architecture** for disciplined execution:

- **Micro-file Design**: Each step is self-contained and followed exactly
- **Just-In-Time Loading**: Only load the current step file
- **Sequential Enforcement**: Complete steps in order, no skipping
- **Write-as-you-go**: Each analysis step writes its section straight into `HANDOVER.md`, then purges the raw findings from context — keep only a one-line summary so long codebases do not exhaust context. (For small/medium codebases you may instead keep findings in context so cross-section references — e.g. a pitfall in §6 citing a flow stage in §3 — stay consistent; the purge is an optimization for large codebases, not a mandate.)

### Step Processing Rules

1. **READ COMPLETELY**: Read the entire step file before acting
2. **FOLLOW SEQUENCE**: Execute sections in order
3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human
4. **LOAD NEXT**: When directed, read fully and follow the next step file

### Critical Rules (NO EXCEPTIONS)

- **NEVER** load multiple step files simultaneously
- **NEVER** modify the project's source code — this workflow is read-only over the codebase; it only writes the handover manual under `{project_knowledge}`
- **ALWAYS** cite evidence as `file:line` (or `file`) for every concrete claim; mark anything you could not verify as an inference to confirm with the original author
- **ALWAYS** halt at checkpoints and wait for human input — UNLESS autonomous mode is on (see below)
- **Autonomous / non-interactive mode**: if the caller sets `autonomous = true`, or the trigger explicitly asks to run without stopping (e.g. "自动跑完", "don't stop to ask"), do NOT halt at any CHECKPOINT. Proceed using the best available default (scope = whole project unless specified; chain shortlist = the top candidates you ranked), and record every assumption you made in the final summary instead of asking.

### Optional: parallel deep scans

If your runtime supports launching parallel sub-agents (e.g. a Task tool), you MAY delegate the four deep scans (business flows, third-party integrations, design & trade-offs, pitfalls & legacy) to parallel read-only sub-agents to manage context, then merge their structured findings. This is an optimization, not a requirement — if unavailable, run the steps sequentially with write-as-you-go.

## FIRST STEP

Read fully and follow: `./steps/step-01-scope-and-orient.md`