---
scope: '' # set at runtime: "whole-project" | "module:<path>" | "flow:<name>"
output_dir: '' # set at runtime: resolved {project_knowledge}
handover_doc: '' # set at runtime: {output_dir}/HANDOVER.md
git_ref: '' # set at runtime: current commit / "no-vcs"
priority_flows: '' # set at runtime: business flows the user wants prioritized
autonomous: false # set true by the caller to auto-proceed at every CHECKPOINT without halting
---

> These frontmatter fields are **in-memory working variables** for this run. There is no file to write them back to — carry their values forward across steps in context. `autonomous` may be set by the caller (or inferred from a "run without stopping" trigger).

# Step 1: Scope & Orient

## RULES

- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
- YOU MUST ALWAYS WRITE all artifact content in `{document_output_language}`
- This whole workflow is **read-only over the project's source code**. You only write the handover manual under `{project_knowledge}`.
- The prompt that triggered this workflow IS the intent — treat any path / module / flow named in it as the scope, do not re-ask if it is already clear.
- Cite `file:line` for concrete claims. This step only builds the map; the deep passes come later.

## INSTRUCTIONS

### 1. Resolve output location and baseline

1. Set `{output_dir}` = resolved `{project_knowledge}`. Set `{handover_doc}` = `{output_dir}/HANDOVER.md`.
2. If `{handover_doc}` already exists, ask the user: **overwrite / start fresh** or **cancel**. Do not silently clobber prior work.
3. Capture `{git_ref}`: if a Git repo, run `git rev-parse --short HEAD` and `git symbolic-ref --short HEAD` (or note detached HEAD). If no VCS, set `{git_ref}` = `"no-vcs"`.

### 2. Determine scope

Determine `{scope}` from the triggering prompt and recent conversation. If still ambiguous: when `{autonomous}` is false, HALT and ask the user to pick; when `{autonomous}` is true, default to **whole project** and record the assumption for the final summary. The choices:

- **Whole project** — handover for the entire codebase
- **A module / subsystem / path** — handover scoped to one area (ask for the path)
- **A specific business flow** — center the handover on one named flow (e.g. "对账", "受理")

Also ask (one combined question, skip what the prompt already answered; skip entirely if `{autonomous}` is true):

- Any **business flows to prioritize**? (store as `{priority_flows}`) — e.g. 业务受理、规则校验、对账、回写
- Who is the **audience** — a new team member, or an external/outgoing handover? (tunes how much in-house context to spell out)

### 3. Reuse what already exists (do NOT re-derive)

Scan for and load *summaries* of prior knowledge so you build on it instead of redoing architecture work:

- `document-project` output in `{output_dir}`: `index.md`, `project-overview.md`, `architecture*.md`, `source-tree-analysis.md`, `data-models*.md`, `api-contracts*.md`
- `README*`, `CONTRIBUTING*`, `docs/`, `ARCHITECTURE*`, ADRs (`docs/adr/`, `doc/decisions/`), `CHANGELOG*`
- `**/project-context.md`, `CLAUDE.md`, in-repo wikis

Keep only a one-paragraph summary of each in context. If `architecture.md` exists, treat its tech-stack/topology as given and move faster.

### 4. Orient: build the map (lightweight, no deep tracing yet)

Establish the skeleton the later passes will hang off:

- **Tech stack:** detect languages, frameworks, ORM/data layer, build tool, runtime, key versions — from manifests (`package.json`, `pom.xml`, `build.gradle`, `go.mod`, `requirements.txt`, `Gemfile`, `*.csproj`) and lockfiles.
- **How to run:** install / start / build / test commands (from manifests, scripts, README, Makefile, Dockerfile, compose).
- **Entry points / external-comm surfaces** (these seed Step 2): controllers/routes, RPC/gRPC services, MQ consumers/listeners, scheduled jobs/cron, CLI commands, webhook/callback receivers, event handlers, app bootstrap/main.
- **Data stores:** primary/replica DBs, cache, message broker, object storage, search — from config + client wiring.
- **Module responsibility map:** top-level modules/packages/services, each with its responsibility, key directory, exposed surface, and main dependencies. A Mermaid `graph LR` of module dependencies is welcome.
- **Glossary seed:** start a running list of non-obvious terms / abbreviations / status enums / table names you encounter (carried forward to Step 6).

Use glob/grep and read only the files needed to map the above — do NOT exhaustively read source yet.

### 5. Create the handover skeleton

1. Read `../templates/handover-template.md`.
2. Substitute the top-matter variables (`{{project_name}}`, `{{date}}`, `{{scope}}`, `{{user_name}}`, `{{git_ref}}`).
3. Fill **Section 1 (Orientation)** and **Section 2 (Module Responsibility Map)** now, from step 4 above. Write real content in `{document_output_language}`. Keep the template's bilingual section headers as-is — only the body content you author follows `{document_output_language}`.
4. Leave the `<!-- FILL: ... -->` markers for sections 3–11 in place (later steps fill them).
5. Write the result to `{handover_doc}`.

## CHECKPOINT

Present to the user, in `{communication_language}`:

- Resolved scope, output path, and code baseline
- The detected tech stack + how-to-run
- The module responsibility map (table or list)
- The list of candidate entry points you will trace in Step 2, and which flows are prioritized

If `{autonomous}` is false: HALT and ask the user to confirm or correct the scope, module map, and priority flows before proceeding; incorporate corrections into `{handover_doc}` sections 1–2.

If `{autonomous}` is true: skip the HALT — proceed with the detected scope and map, and note any assumptions for the Step 6 summary.

## NEXT

Read fully and follow `./step-02-business-flows.md`