# Handover

> Handover is an Agent Skill for productivity published in the me2resh/apexyard repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Onboard an external repo via a structured handover assessment + harnessability scoring across 5 codebase dimensions.

- Skill name: `handover`
- Category: [Productivity](https://www.openparable.com/skill/productivity/1)
- Source: https://github.com/me2resh/apexyard/blob/HEAD/.claude/skills/handover/SKILL.md
- Repository: me2resh/apexyard (479 GitHub stars when collected)

## SKILL.md

# /handover — External Repo Handover Assessment

Adopt an external repo into ApexYard management. The skill reads the target repo, synthesises a structured handover document, and tells you which ApexYard roles, workflows, and hooks should kick in.

This is the bridge between "we just inherited this codebase" and "this codebase is now governed by our normal SDLC".

## LSP-aware (optional, recommended)

The handover deep-dive — reading the codebase to populate the assessment — performs semantic code navigation: finding definitions, walking references, tracing handlers across modules. When a Git URL is given, the skill clones the repo into `workspace/<name>/` at step 1.5-clone (default, before any reads begin). With LSP enabled (`ENABLE_LSP_TOOL=1` + per-language plugin per `docs/getting-started.md`) **and** the repo cloned locally, queries are ~3-15× cheaper in token cost than grep + Read on shallow lookups, and ~1.4-5× cheaper on multi-hop traces. Without LSP — or when only metadata is available — the skill falls back to grep + Read transparently. No new failure mode, just optional speed during the deep-dive phase.

Per-language LSP plugins live in Claude Code's marketplace. Install once; the skill detects the active language and dispatches automatically.

## Path resolution

Read the registry path via `portfolio_registry`, the per-project docs dir via `portfolio_projects_dir`, and the ideas backlog via `portfolio_ideas_backlog` — all from `.claude/hooks/_lib-portfolio-paths.sh`. Source the helper at the top of any bash block that touches those paths:

```bash
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
projects_dir=$(portfolio_projects_dir)
registry=$(portfolio_registry)
```

Defaults match today's single-fork layout (`./apexyard.projects.yaml`, `./projects`, `./projects/ideas-backlog.md`). Adopters in split-portfolio mode override the `portfolio.{registry, projects_dir, ideas_backlog}` keys in `.claude/project-config.json`. Don't hardcode literal `apexyard.projects.yaml` or `projects/` paths in bash blocks — the helper resolves whichever mode the adopter is in. See `docs/multi-project.md`.

**Write targets** (see me2resh/apexyard#373 + #443): paths documented as `projects/<name>/X` in this skill are canonical adopter-facing forms — implement them in bash as `"${projects_dir}/<name>/X"`. Never construct from `"${PWD}/projects/..."`, `"$(git rev-parse --show-toplevel)/projects/..."`, or a literal `./projects/...` — those break in split-portfolio v2 mode where `projects_dir` resolves to a sibling repo.

**REQUIRED per-block preamble** (see #443): Claude executes each ```bash``` block as a separate shell invocation. The `projects_dir` assignment from the Path resolution section above does NOT carry into later blocks. Every bash block that writes to a `projects/<name>/X` path MUST start with this three-line preamble so it's self-contained:

```bash
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
projects_dir=$(portfolio_projects_dir)
# ... now write to "${projects_dir}/<name>/X"
```

The Path resolution section's example sources the helper *once* for documentation purposes; it does not absolve later blocks from sourcing it themselves. Treat each ```bash``` fence as a fresh process.

## Usage

```
/handover legacy-billing-api
/handover legacy-billing-api ../legacy-billing-api
/handover marketing-site https://github.com/some-org/marketing-site
/handover marketing-site --topology typescript-nextjs
/handover legacy-billing-api --all          # non-interactive: generate the full default set
/handover legacy-billing-api --interactive  # explicit opt-in to the checklist (same as default)
```

The `--topology <name>` flag pre-selects a topology bundle and skips the interactive pick in step 1.5. Available v1 topologies: `typescript-nextjs`, `python-fastapi`, `go-data-pipeline`. See [`topologies/README.md`](../../../topologies/README.md) and AgDR-0048.

### Document-set flags (`--all` vs `--interactive`) — default is the checklist

By default the skill presents a **document selection checklist** (step 5.6) after the assessment is computed, so the operator opts in to exactly the artefacts they want and picks the template for each template-backed doc. Two flags override the prompt:

| Flag | Behaviour |
|------|-----------|
| `--all` | **Non-interactive.** Generate the full default set with no checklist and the conventional template for each template-backed doc — byte-for-byte the pre-checklist behaviour. Use this for scripted / unattended runs or when you just want everything. |
| `--interactive` (default) | Present the checklist + per-doc template pick. Equivalent to passing no flag. The flag exists so the default is nameable in scripts and docs. |

Default is `--interactive` because a handover rarely needs every artefact, and the wrong template choice on a template-backed doc is annoying to undo by hand. `--all` is the explicit escape that preserves today's muscle memory — existing invocations that pass neither flag now see the checklist; pass `--all` to keep the old no-prompt flow. The handover assessment + harnessability score are **always** generated regardless of flag — they are the skill's core output, not optional artefacts.

## Output location

The skill always writes the handover assessment; the rest of the artefacts are **selected via the step 5.6 checklist** (or generated in full with `--all`):

```
projects/<name>/handover-assessment.md         ← always (re)written (assessment + harnessability)
projects/<name>/architecture/container.md      ← if selected + missing — stub L2 C4 diagram (default-ticked)
projects/<name>/architecture/context.md        ← if selected + missing — stub L1 C4 diagram
projects/<name>/architecture/sequence-<flow>.md ← if selected + a clear flow exists
```

Richer artefacts the operator can select but which are owned by dedicated skills — DFD (`/dfd`), Feature Inventory (`/extract-features`), user-journey HTML (`/journey`), Architecture Vision (`/tech-vision`) — are **handed off** rather than generated inline (see step 5.6).

One **opt-in (default-OFF)** artefact is written into the **target repo** instead of the ops fork — the in-repo operating manual:

```
<target repo>/AGENTS.md         ← if selected (default-OFF) + not already present — concise agent operating manual, delivered via a branch + PR (step 8.5)
<target repo>/CLAUDE.md         ← only if no CLAUDE.md exists — a one-line `@AGENTS.md` import shim
```

This is the single exception to "read-only against the target repo" (Rule 1) — it is opt-in, confirmed per run, and PR-delivered (never a direct commit). See step 8.5 and AgDR-0073.

The folder lives in the ops repo (your fork of apexyard), alongside the rest of `projects/`.

If `projects/<name>/` doesn't exist, create it. Also seed a `projects/<name>/README.md` stub if missing — see `projects/README.md` for the convention.

The architecture stub is **written once** and never overwritten — it's a starting point, not a generated artefact. After the first handover, any edits the team makes to refine the diagram survive re-runs of the skill.

## Process

### 0. Mark this session as bootstrap (REQUIRED)

`/handover` may run before any tracker tickets exist for the project being adopted, so the `require-active-ticket.sh` PreToolUse hook would block the registry / `projects/<name>/` writes the skill needs. Write a marker so the hook exempts this skill (it's on the default `bootstrap_skills` list in `.claude/project-config.defaults.json`):

```bash
mkdir -p .claude/session && echo "handover" > .claude/session/active-bootstrap
```

Clear the marker on completion (Step "Post-Handover Checklist" below). If the skill is interrupted, the SessionStart hook `clear-bootstrap-marker.sh` clears it at the start of the next session. See AgDR-0011 + me2resh/apexyard#150.

### Bootstrap scope — what IS and IS NOT exempt

The bootstrap exemption covers ONLY these writes:

- `apexyard.projects.yaml` — registry append (step 7)
- `projects/<name>/` — assessment, architecture stubs (container / context / sequence), README (steps 5, 6, 6.1)
- `.claude/session/active-bootstrap` — the marker itself (step 0)
- Topology instantiation files (step 5.5, if a topology is picked)

It does NOT cover:

- Palette changes, UI work, or any other user request made during the session
- Creating or pushing new repositories
- Commits to branches without a ticket

If the user requests work outside the handover's scope mid-session, tell them: "That's outside the handover's bootstrap exemption — let me /start-ticket first." Then follow the normal SDLC: ticket → branch → PR → review.

### 1. Locate the target repo

If a path is given, use it. If a URL is given, proceed immediately to clone it into `workspace/<name>/` (see step 1.5-clone below) — the user does not need to clone manually. If nothing is given, ask:

```
Where is the target repo? Local path or git URL?
```

### 1.5-clone. Clone the repo (URL path only — default yes)

When the operator provides a Git URL (step 1), clone it immediately before doing any further reads. Default is **yes** — no confirmation needed unless the operator explicitly passes `--no-clone` on the skill invocation. This is the cheapest moment: subsequent reads in steps 2–6 are 3–15× cheaper per query against a local clone than via the GitHub API.

#### Resolve the workspace dir and clone

```bash
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
WORKSPACE_DIR=$(portfolio_workspace_dir)
mkdir -p "$WORKSPACE_DIR"

if [ -d "$WORKSPACE_DIR/<name>/.git" ]; then
  echo "✓ $WORKSPACE_DIR/<name>/ already exists — skipping clone."
else
  git clone <repo-url> "$WORKSPACE_DIR/<name>"
fi
```

In single-fork mode `WORKSPACE_DIR` resolves to `<ops-root>/workspace`; in split-portfolio v2 mode it resolves to the sibling private repo (e.g. `../<fork>-portfolio/workspace`). Don't hardcode `workspace/<name>/`.

#### On clone failure

If the clone fails (private repo without credentials, network error, repo moved): report the exit code, point at `gh auth login` or a manual `git clone <repo-url> "$WORKSPACE_DIR/<name>"` as the recovery, and continue with the local-path fallback. Do **not** retry or invent an alternative URL. The operator picks up from there.

If the operator explicitly passed `--no-clone` on the `/handover` invocation, skip this step silently and set `$CLONE_STATUS="declined"` for the step 10 summary.

#### Set the clone marker

```bash
CLONE_STATUS="cloned"   # or "preserved" | "declined" | "failed: <reason>"
```

All subsequent reads in steps 2–6 use `$WORKSPACE_DIR/<name>/` as the repo root whenever `$CLONE_STATUS` is `cloned` or `preserved`. When `$CLONE_STATUS` is `declined` or `failed`, fall back to GitHub API reads via `gh api` / `gh -R <owner/name> …` (degraded but functional).

### 1.5-reindex. Reindex the cloned repo in MCP (default: always attempt)

After a successful clone (`$CLONE_STATUS=cloned`), trigger an MCP reindex so `search_code` and `search_docs` return results during the deep-dive phases that follow (steps 2–6). Without this step those queries return empty against the just-cloned repo, and the agent silently falls back to `find` + `cat` + `Bash` — defeating the token-cost benefit of cloning early.

```
mcp__apexyard-search__reindex(scope="project", project="<name>")
```

**On MCP unavailable:** the call will error. Catch the error, print a single-line warning, set the marker, and continue. **Do not skip silently** — silent skips are indistinguishable between "server down" and "agent forgot the step", and the second failure mode is what this step exists to prevent.

```
⚠ MCP reindex unavailable — falling back to grep + Read for steps 2–6
```

```bash
REINDEX_STATUS="indexed"   # or "unavailable" | "skipped" (when $CLONE_STATUS != cloned)
```

When `$REINDEX_STATUS="indexed"`, prefer `search_code` and `search_docs` over `grep` + `Read` for the assessment reads in steps 2–6 (per the MCP-search-first rule). When `unavailable` or `skipped`, fall back to `grep` + `Read` without further apology.

A `PostToolUse` hook (`suggest-mcp-reindex-after-clone.sh`) fires after the clone command and emits a one-line reminder of this step. Same advisory shape as `detect-role-trigger.sh` — exit 0, non-blocking, removes the "I forgot the rule applied here" failure mode.

### 1.5. Pick a topology (default: skip / custom)

ApexYard ships **harness-template topologies** — bundles of curated handbooks + CI pipelines + AgDR templates per service shape. Picking one here pre-bakes the right governance surface for the stack; declining keeps the existing flow byte-for-byte. See [`topologies/README.md`](../../../topologies/README.md) and AgDR-0048.

If the operator passed `--topology <name>` on the CLI, skip the interactive prompt and use that pick. Otherwise prompt:

```
Which topology fits this project?

  [1] typescript-nextjs   — TypeScript + Next.js web app (App Router, Prisma, JWT)
  [2] python-fastapi      — Python + FastAPI service (Pydantic v2, SQLAlchemy async, JWT)
  [3] go-data-pipeline    — Go batch / streaming pipeline (no HTTP surface)
  [4] Skip / custom       — no topology bundle; use the framework defaults

Read topologies/<name>/README.md for what each bundle includes.

[1/2/3/4 — default 4]
```

**Branching:**

- **Pick 1/2/3:** record the topology name in `$PICKED_TOPOLOGY` (e.g. `typescript-nextjs`). Verify the topology dir exists at `<ops_root>/topologies/<name>/`. If missing (e.g. operator on an older framework version), print `⚠ topology dir not found — falling back to no bundle` and continue with `$PICKED_TOPOLOGY=""`.
- **Pick 4 / default / any other input:** set `$PICKED_TOPOLOGY=""`. Continue exactly as the pre-topology flow.

**Verifying the pick.** Read the topology's `README.md` and `VERSION` files. Print a one-line confirmation:

```
Topology: typescript-nextjs v1.0.0 — will instantiate 11 files into projects/<name>/ and workspace/<name>/.github/workflows/. (See step 5.5.)
```

If `$PICKED_TOPOLOGY=""`, print nothing — the rest of the flow is unchanged.

### 1.6. Harness selection (skippable)

Background. As of 2026-07-09 the framework's mechanical gates reach beyond Claude Code through thin per-harness adapters — see `docs/harnesses/README.md`, the single source of truth for the support matrix. A team adopting an existing repo may already be running (or want to run) a non-Claude-Code harness against it; this step surfaces the adapter path at handover time instead of leaving the adopter to discover `docs/harnesses/` on their own. Light and skippable — Claude Code adopters (the default) answer one question and move on.

Ask:

```
Which harness(es) will drive work on {name}?
  [1] Claude Code (default — the native, full experience)
  [2] opencode
  [3] pi (pi.dev)
  [4] Codex
  [5] Cursor
  [6] Other / not sure

[1-6, comma-separated for more than one — default 1]
```

**Branch on the answer:**

- **1 / default / empty** → continue straight to step 2. No further output.
- **6** → one line — *"No adapter for that harness yet. The mechanical gates (`.claude/hooks/*.sh`) are portable bash; see `docs/harnesses/README.md` § 'Adapter-authoring pattern for future harnesses' if you want to write one."* — then continue to step 2.
- **2 / 3 / 4 / 5 (one or more)** → for each, print its install command + its one precondition, read fresh from `docs/harnesses/README.md` (single source of truth — don't duplicate the matrix here as a maintained copy). As of the 2026-07-09 matrix:

  | Harness | Install | Precondition | Tier |
  |---------|---------|---------------|------|
  | opencode | `bash bin/install-opencode-adapter.sh` | run opencode headless with `--auto` | ✅ live-proven |
  | pi | `bash bin/install-pi-adapter.sh` | run pi headless with `-a` / `--approve` | ✅ live-proven |
  | Codex | `bash bin/sync-codex-adapter.sh` | grant hook-trust — `/hooks` interactively, `--dangerously-bypass-hook-trust` for a one-off headless run, or a user-level `~/.codex/hooks.json` | ✅ live-proven |
  | Cursor | `bin/install-cursor-adapter.sh` | installs to **user-level** `~/.cursor/hooks.json` | 🟡 **failClosed-only** — not live-proven; the `cursor-agent` CLI ignores hooks entirely |

  **Honesty is load-bearing — never round Cursor up.** State the tier exactly as `docs/harnesses/README.md` does: opencode/pi/Codex are live-proven (a real credentialed model turn was actually blocked by the delegated gate); Cursor only *fails closed* on a hook-runner error, a materially weaker guarantee than verified delegated execution. Link the per-harness page for the full workflow: `docs/harnesses/<harness>.md`.

**Don't run the install command yourself** — print it, don't execute `bin/install-*-adapter.sh` against the target repo on the operator's behalf. Adapter install is a decision for the team taking ownership, not a side effect of adoption.

Record the pick as `$SELECTED_HARNESSES` (comma-separated, or `claude-code` if 1/default) for the step 10 summary.

### 2. Read the surface area

Use `$WORKSPACE_DIR/<name>/` as `<repo>` when available (clone succeeded or path was given). Fall back to GitHub API reads only when `$CLONE_STATUS` is `declined` or `failed`. Local reads are preferred — they are cheaper and more complete.

Without running anything destructive, gather:

```bash
# Tree (top 2 levels, prune node_modules / .git)
find <repo> -maxdepth 2 -type d \
  ! -path '*/node_modules*' \
  ! -path '*/.git*' \
  ! -path '*/dist*' \
  ! -path '*/build*'

# Key files
ls <repo>/README* <repo>/package.json <repo>/pyproject.toml \
   <repo>/Cargo.toml <repo>/go.mod <repo>/Gemfile 2>/dev/null

# CI config
ls <repo>/.github/workflows/ 2>/dev/null

# Last commit & contributors
git -C <repo> log -1 --format='%h %ai %an %s'
git -C <repo> shortlog -sn --no-merges | head -10

# Open issues / PRs (if it's a GitHub repo — always from the API regardless of clone status)
gh -R <owner/name> issue list --state open --json number,title,labels --limit 10
gh -R <owner/name> pr list --state open --json number,title --limit 10
```

### 3. Detect the tech stack

Look at:

- `package.json` → Node ecosystem; check `engines`, `scripts`, `dependencies`
- `pyproject.toml` / `requirements.txt` → Python
- `Cargo.toml` → Rust
- `go.mod` → Go
- `Gemfile` → Ruby
- `Dockerfile` → containerised; what base image?
- `.github/workflows/` → existing CI; how mature?
- `tsconfig.json` strictness, presence of tests, presence of linters

### 4. Try a build (optional, ask first)

```
Should I attempt to build the project to check current health? (y/n)
```

If yes and it's a Node project: `npm install --ignore-scripts && npm run build` (or whatever the package.json scripts say). Capture pass/fail and any errors.

### 4.5. Harnessability assessment

> Why this exists. ApexYard's value as a "harness" depends on the codebase having the ambient affordances the framework's rules and handbooks expect — type safety, module boundaries, lint baselines, etc. When those are missing, Rex's architecture handbooks (especially `ENFORCEMENT: blocking` ones like clean-architecture-layers) fire false positives and create review noise rather than catching real issues. Naming that gap during adoption — rather than after the first noisy code review — gives the operator a chance to either adopt advisory-only, or schedule the scaffolding work as a follow-up. This step codifies the assessment so a `low` score becomes a visible warning at adoption time, not a surprise.
>
> The framing draws on industry-standard harness-engineering prior art on **ambient affordances** — the idea that a tool's effectiveness depends on the working environment already supplying the signals the tool relies on. See AgDR-0042.

Score 5 codebase dimensions, each with a 1-line rationale citing the evidence found in steps 2-4. Combine into an overall verdict (high / moderate / low) using the truth table below. If `low`, print the warning text verbatim. Persist the result in the handover assessment file (step 5).

#### The 5 dimensions

| # | Dimension | What to check (examples per language) | Verdict |
|---|-----------|----------------------------------------|---------|
| 1 | **Type safety** | TS: `tsconfig.json` with `"strict": true` (or all `strict*` flags set). Ruby: `sorbet/` dir + `# typed:` sigils in src files. Python: `mypy.ini` OR `[tool.mypy] strict = true` in `pyproject.toml` OR `pyrightconfig.json` strict. Go: implicitly strong (assume `strong`). Rust: implicitly strong (assume `strong`). | `strong` / `partial` / `none` |
| 2 | **Module boundaries** | Presence of `src/domain/` + `src/application/` + `src/infrastructure/` (clean-architecture); presence of `packwerk.yml` + `packs/` (Ruby Packwerk); monorepo workspace config (`package.json` `workspaces:`, `pnpm-workspace.yaml`, `nx.json`, `turbo.json`) indicating package-level boundaries. Otherwise flat single-`src/`. | `strong` / `partial` / `flat` |
| 3 | **Framework opinionation** | `package.json` deps containing Next.js / NestJS / Remix (TS strong); `pom.xml` / `build.gradle` containing Spring (Java strong); `requirements.txt` / `pyproject.toml` containing Django / FastAPI (Python strong / moderate respectively); `Gemfile` containing Rails (Ruby strong); `go.mod` containing Gin / Echo (Go moderate) vs raw `net/http` only (weak). Strong = full opinionation (persistence + HTTP + DI / conventions). Moderate = HTTP framework only. Weak = raw scripts, no framework. | `strong` / `moderate` / `weak` |
| 4 | **Test coverage signal** | `jest.config.*` with a `coverageThreshold` block; `.nycrc` (Istanbul) with thresholds; `pytest.ini` / `setup.cfg` / `pyproject.toml` containing `--cov` or `[tool.coverage]`; `vitest.config.*` with `coverage.thresholds`; Go CI step running `go test -cover`; coverage step / threshold in any `.github/workflows/*.yml` or `.gitlab-ci.yml`. | `present` / `absent` |
| 5 | **Lint baseline** | ESLint config (`.eslintrc.*`, `eslint.config.*`); RuboCop (`.rubocop.yml`); golangci-lint (`.golangci.yml`); ruff / flake8 / pylint config (or `[tool.ruff]` etc. in `pyproject.toml`); `.pre-commit-config.yaml` with any linter hook. | `present` / `absent` |

Each dimension MUST be backed by a one-line rationale citing the evidence path and key signal, e.g.:

```
- Type safety: strong — tsconfig.json line 6: "strict": true
- Module boundaries: flat — only src/, no domain/application/infrastructure dirs
- Framework opinionation: moderate — package.json has express but no ORM/DI framework
- Test coverage signal: absent — no coverageThreshold in jest.config.js, no coverage step in .github/workflows/
- Lint baseline: present — .eslintrc.json at repo root
```

#### Overall verdict (truth table)

Count how many of the 5 dimensions are `strong` or `present` (the "good" buckets):

| Strong-or-present count | Other conditions | Verdict |
|-------------------------|------------------|---------|
| 5 / 5 | — | `high` |
| 3 or 4 / 5 | — | `moderate` |
| ≤ 2 / 5 | — | `low` |
| any | Type safety is `none` AND framework opinionation is `weak` | `low` (override — these two together amplify each other) |

Implement the rule as a bash-shaped truth table so re-implementations agree:

```bash
# Pseudocode — dimension verdicts as variables
# Each is one of: strong/partial/none, strong/partial/flat,
#                 strong/moderate/weak, present/absent, present/absent
good=0
[ "$type_safety"        = "strong"  ] && good=$((good+1))
[ "$module_boundaries"  = "strong"  ] && good=$((good+1))
[ "$framework_opinion"  = "strong"  ] && good=$((good+1))
[ "$test_coverage"      = "present" ] && good=$((good+1))
[ "$lint_baseline"      = "present" ] && good=$((good+1))

if [ "$type_safety" = "none" ] && [ "$framework_opinion" = "weak" ]; then
  verdict="low"
elif [ "$good" -ge 5 ]; then
  verdict="high"
elif [ "$good" -ge 3 ]; then
  verdict="moderate"
else
  verdict="low"
fi
```

These thresholds are deliberately conservative for v1 — `high` requires every dimension to be in the top bucket. See AgDR-0042 for the rationale and tuning notes.

#### Warning text (only when verdict is `low`)

Print this text **verbatim** to the operator after the assessment, and also embed it inside the handover-assessment.md file under the "Harnessability assessment" section:

```
⚠ Harnessability: LOW

Rex's architecture handbooks will fire advisory-only on this codebase. The blocking gate (`ENFORCEMENT: blocking`) will generate false positives. Recommended: adopt as advisory-only, plan a follow-up to add the missing scaffolding (typescript strict, lint baseline, etc.)
```

For `high` and `moderate` verdicts, do NOT print the warning — the score in the assessment file is enough.

#### What this step does NOT do

- Does **not** auto-fix the missing scaffolding. Adding TS strict, ESLint, coverage thresholds, etc. is out of scope and must be filed as a follow-up by the operator.
- Does **not** apply per-team / per-stack weights to the dimensions. v1 is universal; per-team tuning is deferred.
- Does **not** track the score over time. The score lives in the handover-assessment.md only; re-running `/handover` re-scores from the live tree.

See AgDR-0042 for the dimensions + thresholds rationale, the alternatives considered, and the legacy-adopter sensitivity.

### 5. Synthesise the assessment

Write `projects/<name>/handover-assessment.md`:

````markdown
# {name} — Handover Assessment

**Date**: YYYY-MM-DD
**Assessor**: {git user}
**Status**: handover

## Origin

- **Where it came from**: {acquisition / inherited team / open source / contractor / etc.}
- **Original owner**: {if known}
- **Repo location**: {URL or path}
- **First commit date**: {from git log}
- **Last commit date**: {from git log}

## Current State

### Tech stack
- Language: {…}
- Runtime: {…}
- Framework: {…}
- Database: {…}
- Test framework: {…}
- CI: {…}

### Build status
- `npm install`: {ok / failed}
- `npm run build`: {ok / failed / not attempted}
- `npm run test`: {ok / failed / not attempted}
- `npm run lint`: {ok / failed / not attempted}

### Test coverage
- Estimated: {…} (from coverage report if available, otherwise "unknown")

### Repo activity
- Commits in last 90 days: {…}
- Open issues: {…}
- Open PRs: {…}
- Top contributors: {…}

## Harnessability assessment

**Overall verdict**: `{high | moderate | low}`

{If `low`, embed the warning block verbatim here:}

> ⚠ Harnessability: LOW
>
> Rex's architecture handbooks will fire advisory-only on this codebase. The blocking gate (`ENFORCEMENT: blocking`) will generate false positives. Recommended: adopt as advisory-only, plan a follow-up to add the missing scaffolding (typescript strict, lint baseline, etc.)

| Dimension | Score | Evidence |
|-----------|-------|----------|
| Type safety | `{strong / partial / none}` | {1-line rationale citing the path + key signal, e.g. `tsconfig.json line 6: "strict": true`} |
| Module boundaries | `{strong / partial / flat}` | {1-line rationale, e.g. `src/domain/ + src/application/ + src/infrastructure/ all present`} |
| Framework opinionation | `{strong / moderate / weak}` | {1-line rationale, e.g. `package.json deps include @nestjs/core (DI + HTTP + persistence opinionation)`} |
| Test coverage signal | `{present / absent}` | {1-line rationale, e.g. `jest.config.js has coverageThreshold: { global: { lines: 80 } }`} |
| Lint baseline | `{present / absent}` | {1-line rationale, e.g. `.eslintrc.json present at repo root`} |

See AgDR-0042 for the scoring rationale and v1 thresholds.

## Quality Risks

### Security
- {known CVEs in deps, hardcoded secrets, missing auth, etc.}

### Dependencies
- {abandoned packages, major versions behind, license issues}

### Technical debt
- {missing tests, no types, dead code, tangled architecture, etc.}

### Operational
- {missing CI, no monitoring, no deploy automation, etc.}

## Integration Plan

### Roles that apply
- {tech-lead, backend-engineer, frontend-engineer, sre, security-auditor, …}

### Workflows that kick in
- [ ] PR workflow (`.claude/rules/pr-workflow.md`) — every change goes through a PR
- [ ] AgDR for technical decisions
- [ ] Code Reviewer agent on every PR
- [ ] Security Reviewer agent on first pass and high-risk PRs
- [ ] `/audit-deps` on adoption and monthly thereafter

### Hooks to enable
- [ ] `block-git-add-all`
- [ ] `block-main-push`
- [ ] `validate-branch-name` (set `ticket_prefix` for this project's tracker)
- [ ] `validate-pr-create`
- [ ] `pre-push-gate`
- [ ] `check-secrets`

### CI templates to copy in
- [ ] `golden-paths/pipelines/ci.yml`
- [ ] `golden-paths/pipelines/security.yml`
- [ ] `golden-paths/pipelines/pr-title-check.yml`

### Registry entry

The entry that will be appended to `apexyard.projects.yaml` at the root of the ops repo (see step 7 — the skill does this append for you, with confirmation):

```yaml
- name: {name}
  repo: {owner/name}
  workspace: workspace/{name}
  docs: projects/{name}
  status: handover
  roles:
    {dynamically derived from the tech stack + CI config — see
     "Deriving applicable roles" below}
```

**Deriving applicable roles**: don't hard-code `[tech-lead, backend-engineer]`. Look at the tech stack from step 3:

| Signal | Add role |
|--------|----------|
| Any backend code (package.json with server deps, pyproject.toml, etc.) | `backend-engineer` |
| Any UI code (React/Vue/Svelte, `src/components/`, CSS modules) | `frontend-engineer` |
| CI config detected (`.github/workflows/`, `.gitlab-ci.yml`, etc.) | `platform-engineer` |
| Production deployment evidence (Dockerfile, Terraform, AWS/GCP/Azure SDK) | `sre` |
| Auth / crypto / secrets in the diff | `security-auditor` |
| Always | `tech-lead` |

For a typical handover you'll end up with 3-5 roles in the list.

## Next Steps

Derived dynamically from the Quality Risks found in this assessment. Don't emit generic placeholders — emit specific actions.

Mapping table:

| Risk found | Next step entry |
|------------|-----------------|
| ≥ 1 CVE in deps (any severity) | `1. /audit-deps {name} — triage the {severity} {package} CVE before any new feature work` |
| Failing tests | `2. Fix the {N} failing tests in {module} before merging new PRs (baseline must be green)` |
| No observability (no Sentry/Datadog/CloudWatch/etc.) | `3. /decide on observability ({two most common options for this stack})` |
| Stale CI (no runs in > 30 days) | `4. Re-enable CI on this repo — copy in golden-paths/pipelines/ci.yml` |
| Test coverage unknown | `5. Set up test coverage reporting (vitest/jest coverage config) before the first feature` |
| ≥ 10 open issues | `6. Triage the issue backlog with the previous owner before taking ownership` |
| Missing README or onboarding doc | `7. Write a minimum-viable README (what the project does, how to run it locally, where it deploys)` |

If no risks match a row, omit that row. If fewer than 3 actions come out, add:

- `{next} /code-review the most-recent PR on this repo as Rex to calibrate review standards`
- `{next} Stakeholder sync with the previous owner to cover context the static read couldn't surface`

**Re-handover preservation.** On re-runs of `/handover`, the regenerated `## Next Steps` section MUST preserve any prior-run `~~strikethrough~~ → Filed as [#N](url)` markers on entries that recur in the new list. Detection rule: for each entry that would be emitted by the mapping table above, scan the prior `handover-assessment.md` (if present) for a matching entry by leading verb + key noun phrase (e.g. "Fix the N failing tests in {module}" matches the prior "Fix the M failing tests in {module}" regardless of the count). If matched and the prior version carries a `Filed as` link, preserve the link in the regenerated entry. This is the load-bearing input to step 7.5's filed-marker skip logic — without it, the operator gets re-prompted on every filed entry on every re-handover. See Rule 18.

## Cleanup (REQUIRED before exit)

```bash
rm -f .claude/session/active-bootstrap
```

Always remove the bootstrap marker on a clean exit. If the skill is interrupted before this step, `clear-bootstrap-marker.sh` clears the stale marker on the next session.

## Post-Handover Checklist

Also derived from the risks found. Tailor to the specific repo — don't emit generic items.

- [ ] Review this assessment with the previous owner
- [ ] {top quality risk} — close before the first feature PR
- [ ] {second quality risk} — scheduled in the first 2 weeks
- [ ] Add `{name}` to the weekly `/stakeholder-update` rollup
- [ ] Onboard the roles listed above into the team's on-call / review rotation
- [ ] Set up a test coverage baseline (run `npm test -- --coverage` or equivalent and commit the threshold)
- [ ] Run `/audit-deps {name}` monthly for the next 3 months

## Open Questions

- {anything you couldn't determine from a static read}

````

### 5.5. Instantiate the topology bundle (conditional on step 1.5 pick)

**Skip condition**: if `$PICKED_TOPOLOGY` is empty (operator chose "Skip / custom"), skip this entire step and note in the final summary `topology: skipped`.

If a topology was picked, copy the bundle into the project's instantiation locations. **All copies, never symlinks** — copies are stable across framework updates; `/update` detects drift on top (see AgDR-0048).

#### Resolve paths

```bash
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"

OPS_ROOT="$(git rev-parse --show-toplevel)"
TOPOLOGY_SRC="$OPS_ROOT/topologies/$PICKED_TOPOLOGY"
PROJECTS_DIR=$(portfolio_projects_dir)
WORKSPACE_DIR=$(portfolio_workspace_dir)
TOPOLOGY_VERSION=$(cat "$TOPOLOGY_SRC/VERSION")
```

#### Confirm before any write

Print a per-file plan and prompt for confirmation. This is destructive (creates new files); operator owns the decision.

```
Topology bundle: $PICKED_TOPOLOGY v$TOPOLOGY_VERSION
About to instantiate into the project:

  $PROJECTS_DIR/<name>/handbooks/                     ← all topology handbooks
  $PROJECTS_DIR/<name>/.topology/VERSION              ← version anchor for /update drift detection
  $PROJECTS_DIR/<name>/.topology/name                 ← topology name (one line: $PICKED_TOPOLOGY)
  $PROJECTS_DIR/<name>/docs/agdr/<stack>-<topology>.draft.md   ← stack-specific AgDR template (draft)
  workspace/<name>/.github/workflows/<topology-ci>.yml          ← CI pipeline (only if workspace clone exists)

Existing files at any of these paths will be PRESERVED (no overwrite). If you
want a clean re-instantiation, delete the files and re-run.

Proceed? [Y/n]
```

If the operator declines (`n`), set `TOPOLOGY_INSTANTIATED="declined"` and continue to step 6.

#### Copy handbooks

```bash
mkdir -p "$PROJECTS_DIR/<name>/handbooks"
# rsync if available (handles "preserve target if exists"); fall back to cp -n
if command -v rsync >/dev/null 2>&1; then
  rsync -a --ignore-existing "$TOPOLOGY_SRC/handbooks/" "$PROJECTS_DIR/<name>/handbooks/"
else
  cp -Rn "$TOPOLOGY_SRC/handbooks/." "$PROJECTS_DIR/<name>/handbooks/"
fi
```

The `--ignore-existing` / `-n` flag is load-bearing — adopters who've already started editing handbooks in the project keep their edits.

#### Write the topology anchor (for `/update` drift detection)

```bash
mkdir -p "$PROJECTS_DIR/<name>/.topology"
echo "$PICKED_TOPOLOGY" > "$PROJECTS_DIR/<name>/.topology/name"
cp "$TOPOLOGY_SRC/VERSION" "$PROJECTS_DIR/<name>/.topology/VERSION"
```

`/update` reads these two files to know which topology to diff against (see [`.claude/skills/update/SKILL.md`](../update/SKILL.md) § "Topology drift detection").

#### Seed the AgDR template (as a draft — `.draft.md` extension)

```bash
mkdir -p "$PROJECTS_DIR/<name>/docs/agdr"
TEMPLATE_FILE=$(ls "$TOPOLOGY_SRC/templates/agdr-"*.md 2>/dev/null | head -1)
if [ -n "$TEMPLATE_FILE" ]; then
  TEMPLATE_NAME=$(basename "$TEMPLATE_FILE" .md)
  TARGET="$PROJECTS_DIR/<name>/docs/agdr/${TEMPLATE_NAME}.draft.md"
  [ ! -f "$TARGET" ] && cp "$TEMPLATE_FILE" "$TARGET"
fi
```

The `.draft.md` extension is load-bearing: the AgDR-required hooks ignore `.draft.md` files, so the seed doesn't trigger spurious "AgDR not referenced" findings on the first PR. The operator renames `.draft.md` → `.md` when they fill it in.

#### Copy the CI pipeline (only if `workspace/<name>/` exists locally)

```bash
if [ -d "$WORKSPACE_DIR/<name>/.git" ]; then
  mkdir -p "$WORKSPACE_DIR/<name>/.github/workflows"
  for pipeline in "$TOPOLOGY_SRC/golden-paths"/*.yml; do
    [ -e "$pipeline" ] || continue
    target="$WORKSPACE_DIR/<name>/.github/workflows/$(basename "$pipeline")"
    if [ ! -f "$target" ]; then
      cp "$pipeline" "$target"
    fi
  done
fi
```

If the workspace clone doesn't exist yet (operator hasn't cloned), defer the pipeline copy — emit a one-line note: `topology pipelines pending — clone the repo into workspace/<name>/ then re-run /handover, or copy topologies/$PICKED_TOPOLOGY/golden-paths/*.yml manually`.

#### Set the instantiation marker for the final summary

```bash
TOPOLOGY_INSTANTIATED="$PICKED_TOPOLOGY@$TOPOLOGY_VERSION"
```

### 5.6. Document selection (checklist) — opt in to what gets generated

By this point the **computed core** is done: the handover assessment (step 5) and the harnessability score (step 4.5) are written regardless of any selection. This step decides which of the *additional* generatable artefacts to produce, and — for each template-backed one — which template to render it from.

**Skip condition (`--all`)**: if the operator passed `--all` on the invocation, skip the checklist entirely. Generate the full default set (every row marked "default ✓" in the catalogue below) using each doc's conventional template. Note `document selection: --all (full set)` in the step 10 summary and continue to step 6. This is the byte-for-byte pre-checklist behaviour — existing scripted invocations keep working by adding `--all`.

Otherwise (default, or explicit `--interactive`): present the checklist.

#### Two kinds of output

The catalogue distinguishes two classes — keep them visually distinct in the prompt so the operator knows which ones offer a template pick:

- **Computed / toggle-only** — derived from the repo scan; there is no template to choose, only whether to emit. (Example: the L2 container diagram is *assembled* from detected signals, but it still renders **through** the `architecture/c4-container.md` template — so it's template-backed, see below. The handover assessment itself is pure-computed and is always on, never shown as a toggle.)
- **Template-backed / choose-a-template** — rendered from a file in the template library. For these the operator gets a second sub-prompt to pick which resolved template to use (framework default vs an adopter `custom-templates/**` override, plus any sibling templates that fit the slot).

#### The catalogue

Present this as a numbered checklist. The "default" column marks what `--all` (and the pre-ticked checklist) would generate. Toggle-only rows have no template pick; template-backed rows do.

| # | Artefact | Kind | Template (resolved via `portfolio_resolve_template`) | Default | Generated by |
|---|----------|------|------------------------------------------------------|---------|--------------|
| 1 | L2 container diagram (`architecture/container.md`) | template-backed | `architecture/c4-container.md` | ✓ (if signals + not already present) | step 6 |
| 2 | L1 context diagram (`architecture/context.md`) | template-backed | `architecture/c4-context.md` | — | step 6.1 (`/c4` context pass) |
| 3 | Data Flow Diagram (`architecture/dfd.md`) | template-backed | `architecture/dfd.md` | — | hand off to `/dfd <name>` |
| 4 | Feature Inventory (`feature-inventory.md`) | computed (six-axis scan) | — | — | hand off to `/extract-features <name>` |
| 5 | User-journey preview (`journeys/<flow>.html`) | computed (HTML, from flows) | — | — | hand off to `/journey <name>` |
| 6 | Architecture Vision draft (`architecture/vision.md`) | template-backed | `architecture/vision.md` | — | hand off to `/tech-vision <name>` |
| 7 | Sequence diagram (`architecture/sequence-<flow>.md`) | template-backed | `architecture/sequence.md` | — | step 6.1 (sequence pass) |
| 8 | In-repo `AGENTS.md` (written into the **target repo** via a PR) | computed (from the live assessment) | — | **— (default-OFF)** | step 8.5 (PR into the target repo) |
| 9 | "Governed by ApexYard" README badge (written into the **target repo** via a PR) | computed (badge markdown, two variants) | — | **— (default-OFF)** | step 8.6 (PR into the target repo) |

> The handover assessment + harnessability score are NOT in this catalogue — they are always written (step 5 / 4.5). The catalogue is only the *optional* surface.
>
> **Rows 8 and 9 are special**: they are the only catalogue rows that write into the **target repo** (everything else lands in the ops fork). Both are **default-OFF** so the "read-only against the target repo" rule (Rule 1) stays true unless the operator consciously opts in. When selected, each is delivered via a branch + PR — never a direct commit, never via the ops-fork bootstrap-exempt path. See AgDR-0073 (row 8) and AgDR-0090 (row 9).

Render the prompt like this (pre-tick the default rows; the operator toggles):

```
Document selection for <name>. The handover assessment + harnessability score are
always written. Pick which additional docs to generate (default-ticked shown with [x]):

  [x] 1. L2 container diagram          (template-backed → c4-container)
  [ ] 2. L1 context diagram            (template-backed → c4-context)
  [ ] 3. Data Flow Diagram             (template-backed → dfd)
  [ ] 4. Feature Inventory             (computed — six-axis scan)
  [ ] 5. User-journey preview          (computed — HTML)
  [ ] 6. Architecture Vision draft     (template-backed → vision)
  [ ] 7. Sequence diagram              (template-backed → sequence)
  [ ] 8. In-repo AGENTS.md             (computed → PR into the TARGET repo)
  [ ] 9. "Governed by ApexYard" badge  (computed → PR into the TARGET repo)

Note: items 8 and 9 write into the adopted repo itself (via a branch + PR) — the
only two that do. Both are default-OFF; tick 8 if you want the repo to be
self-describing to agents, tick 9 if you want a visible badge crediting apexyard
governance on the README.

Reply with: 'default' (keep ticks as-is), 'all', 'none',
a comma-list of numbers to GENERATE (e.g. '1,3,4'),
or toggles like '+2 -1' to adjust the defaults.
```

Accept:

- `default` or empty — generate exactly the pre-ticked rows
- `all` — generate every catalogue row (same set as `--all`)
- `none` — generate nothing optional (assessment + harnessability only)
- A comma-list (`1,3,4`) — generate exactly those rows
- Toggle shorthand (`+2 -1`) — start from the defaults, add `+N`, remove `-N`

If the response is ambiguous, ask **one** clarification; on a second ambiguous answer, fall back to `default`.

#### Per-doc template pick (template-backed rows only)

For each **template-backed** row the operator selected, run a template-pick sub-step before generation. Toggle-only / computed rows skip this entirely (there is nothing to pick).

Resolve the candidate templates with the portfolio helper so adopter overrides surface alongside the framework default:

```bash
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"

# Conventional template for this slot (e.g. architecture/c4-container.md).
default_tpl=$(portfolio_resolve_template architecture/c4-container.md)

# Adopter override candidate (only listed when it actually exists — resolve()
# already prefers it, so equality means there's only one real candidate).
registry=$(portfolio_registry)
custom_dir="$(dirname "$registry")/custom-templates"
```

Present the candidates, defaulting to the conventional one:

```
Template for the L2 container diagram:

  [1] c4-container.md            (framework default — templates/architecture/)
  [2] c4-container.md            (adopter override — custom-templates/architecture/)   ← only shown if it exists
  [3] Other library template     (pick any file under templates/architecture/ or custom-templates/architecture/)

[1/2/3 — default 1]
```

Rules for the pick:

- **List the override only when it exists.** `portfolio_resolve_template` already returns the override path when present, so when the custom file is absent, candidate `[2]` is omitted and `[1]` is the sole conventional pick — don't fabricate a second row.
- **Default is always the conventional template** for that slot (candidate `[1]`, or the override if `portfolio_resolve_template` returned it — i.e. the path the helper would pick unprompted). Pressing enter / empty input takes the default. This keeps `--all` and "default" runs byte-stable.
- **`[3] Other`** lets the operator point at any sibling template (e.g. render the container slot from a custom `c4-container-microservices.md` they keep in `custom-templates/architecture/`). Glob `templates/architecture/*.md` + `custom-templates/architecture/*.md`, list them, let the operator choose. If they pick a path that doesn't exist, re-prompt once, then fall back to the default.
- Record the chosen absolute path in a per-doc variable (e.g. `$CONTAINER_TEMPLATE`) and pass it to the generating step instead of re-resolving. Step 6's "Assembling the file" block reads `$CONTAINER_TEMPLATE` when set, falling back to `portfolio_resolve_template architecture/c4-container.md` when the checklist was skipped (`--all`) or the variable is unset.

#### Hand-offs vs in-skill generation

Rows 1, 2, 7 are generated **in this skill** (steps 6 / 6.1). Row 8 (`AGENTS.md`) is also generated in this skill but in a dedicated step (8.5) because it is the only row that writes into the **target repo** via a PR. Rows 3–6 are richer artefacts owned by dedicated skills — for those, the checklist records the selection and, after the summary (step 10), the skill **offers to hand off** to the matching skill rather than reimplementing it:

```
You selected: Data Flow Diagram, Feature Inventory.
Run the owning skills now against the cloned repo?

  /dfd <name>               — Data Flow Diagram
  /extract-features <name>  — Feature Inventory

[y to run in sequence / n to skip — default n]
```

This mirrors step 8's follow-up-skill offer (security/code review) — the checklist never reimplements `/dfd`, `/extract-features`, `/journey`, or `/tech-vision`; it routes to them. On `n`, note the selected-but-deferred docs in the summary so the operator can run them later.

#### Record the selection for the summary

```bash
# Examples — set per the operator's picks
SELECTED_DOCS="container,dfd,feature-inventory"
CONTAINER_TEMPLATE="$default_tpl"   # absolute path chosen in the per-doc pick
```

The step 10 summary reports both the generated set and the deferred (handed-off) set.

### 6. Write the L2 container diagram stub (if selected and missing)

**Selection condition**: generate this file only when row 1 (L2 container diagram) was selected in step 5.6 — i.e. the operator kept it ticked, passed `--all`, or named it in the comma-list. If row 1 was de-selected, skip this step and note `architecture/container.md: skipped (deselected)` in the summary.

**Skip condition**: if `projects/<name>/architecture/container.md` already exists, skip this entire step and note it in the final summary (`architecture/container.md: preserved`). Never overwrite.

If missing: emit a stub Mermaid C4 container diagram derived from the repo signals gathered in step 3. The goal is a file the user can render on GitHub immediately and then refine — correctness beats completeness.

#### Container-detection signals

Scan the repo for these, in order. Stop at the first match per slot where it makes sense (only one `web`, only one primary `db`), but accumulate for multi-service slots (workers, caches, queues can coexist).

**Slot: `web` (frontend / SPA)**

| Signal | Label | Tech label |
|--------|-------|-----------|
| `package.json` has `next` or `@next/*` | Web App | `Next.js` |
| `package.json` has `react-scripts` | Web App | `React / CRA` |
| `package.json` has `vite` + React dep | Web App | `React / Vite` |
| `package.json` has `@remix-run/*` | Web App | `Remix` |
| `package.json` has `svelte` / `@sveltejs/kit` | Web App | `SvelteKit` |
| `package.json` has `nuxt` | Web App | `Nuxt` |
| `package.json` has `@angular/core` | Web App | `Angular` |
| `src/components/` or `src/pages/` exists | Web App | (infer from `package.json`) |

If none match → omit the web container. Not all projects have a frontend.

**Slot: `api` (HTTP backend)**

| Signal | Label | Tech label |
|--------|-------|-----------|
| `package.json` has `express` | API | `Node.js / Express` |
| `package.json` has `fastify` | API | `Node.js / Fastify` |
| `package.json` has `hono` | API | `Node.js / Hono` |
| `package.json` has `@nestjs/core` | API | `NestJS` |
| `package.json` has `koa` | API | `Node.js / Koa` |
| Next.js project with `app/api/` or `pages/api/` | API | `Next.js API routes` (same container as web, or split if clearly separate service) |
| `go.mod` has `net/http` handlers / `gin` / `echo` / `chi` / `fiber` | API | `Go / <framework>` |
| `pyproject.toml` has `fastapi` / `django` / `flask` | API | `Python / <framework>` |
| `Gemfile` has `rails` / `sinatra` | API | `Ruby / <framework>` |
| `Cargo.toml` has `axum` / `actix-web` / `rocket` | API | `Rust / <framework>` |

If the project is a monolith Next.js app with API routes, collapse `web` + `api` into one container labelled `Web App + API` with tech `Next.js` — don't fabricate a split the code doesn't have.

**Slot: `worker` (async / background jobs)**

| Signal | Label | Tech label |
|--------|-------|-----------|
| `package.json` has `bullmq` / `bee-queue` / `agenda` | Background Worker | `Node.js / <lib>` |
| `package.json` has `@inngest/*` | Background Worker | `Inngest` |
| `workers/` directory with job handlers | Background Worker | (infer) |
| `pyproject.toml` has `celery` | Background Worker | `Python / Celery` |

If none → omit.

**Slot: `db` (primary relational / document store)**

| Signal | Label | Tech label |
|--------|-------|-----------|
| `prisma/schema.prisma` with `datasource db { provider = "postgresql" }` | Primary Database | `PostgreSQL (Prisma)` |
| Same, provider = `mysql` / `sqlite` / `mongodb` / etc. | Primary Database | `<Provider> (Prisma)` |
| `drizzle.config.ts` or `drizzle.config.js` | Primary Database | `<driver> (Drizzle)` |
| `knexfile.{js,ts}` | Primary Database | `<client from config> (Knex)` |
| `DATABASE_URL` in `.env.example` with `postgres://` / `mysql://` / `mongodb://` | Primary Database | `<Protocol-derived>` |
| `supabase/config.toml` | Primary Database | `Supabase (PostgreSQL)` |
| `firebase.json` with firestore config | Primary Database | `Firestore` |

Use `ContainerDb(db, ...)` (the `Db` suffix changes the icon in Mermaid C4).

**Slot: `cache`**

| Signal | Label | Tech label |
|--------|-------|-----------|
| `package.json` has `ioredis` / `redis` / `@upstash/redis` | Cache | `Redis` |
| `REDIS_URL` / `UPSTASH_REDIS_URL` in `.env.example` | Cache | `Redis` |
| `package.json` has `memcached` / `memjs` | Cache | `Memcached` |

Use `ContainerDb(cache, ...)`.

**Slot: `queue` (if distinct from `worker`)**

| Signal | Label | Tech label |
|--------|-------|-----------|
| AWS SDK with SQS usage (grep for `@aws-sdk/client-sqs`) | Queue | `AWS SQS` |
| `package.json` has `kafkajs` | Queue | `Kafka` |
| `package.json` has `amqplib` / `@cloudamqp/*` | Queue | `RabbitMQ` |

Only include a separate queue container if it's clearly distinct from worker infrastructure — otherwise fold into the worker's tech label.

**Slot: external systems (from `System_Ext`)**

Infer from:

- Auth SDKs: `@auth0/*` / `@clerk/*` / `next-auth` / `@supabase/auth-*` → `Auth Provider`, tech `Auth0` / `Clerk` / etc.
- Payments: `stripe` / `@paddle/*` → `Payment Processor`
- Email: `postmark` / `@sendgrid/*` / `resend` / `@aws-sdk/client-ses` → `Email Provider`
- Storage: `@aws-sdk/client-s3` / `@vercel/blob` / `@cloudflare/r2` → `Object Storage`
- LLM: `openai` / `@anthropic-ai/sdk` / `@google-ai/*` → `LLM API`

Include only the externals you find evidence for. Don't fabricate a Stripe dependency.

**docker-compose.yml override**

If `docker-compose.yml` exists at the repo root, it's a stronger signal than `package.json` for container composition — the compose services ARE the containers. For each service:

- Map `image: postgres:*` or `image: mysql:*` → `ContainerDb(db, ...)`
- Map `image: redis:*` → `ContainerDb(cache, "Cache", "Redis", ...)`
- Map `image: node:*` / `image: python:*` / `image: ruby:*` with a `build:` context → generic `Container(...)`, use the build context path as a hint
- Map named application services (from `build: ./api`, `build: ./web`) to `api` / `web` slots

When compose and `package.json` conflict, trust compose — it describes the deployment shape the project actually runs in.

**Dockerfile-only**

If there's a `Dockerfile` at repo root but no `docker-compose.yml`: one container, tech = the `FROM` base image (e.g. `node:20-alpine`). Pair it with whatever `package.json` says is the runtime. Don't invent a database container without signal.

#### Assembling the file

Resolve the C4 container template via the portfolio helper so adopter overrides win when present:

```bash
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
# Prefer the template chosen in step 5.6's per-doc pick; fall back to the
# conventional resolution when the checklist was skipped (--all) or unset.
container_template="${CONTAINER_TEMPLATE:-$(portfolio_resolve_template architecture/c4-container.md)}"
```

Single-fork adopters (no `portfolio` block) and adopters with no override fall straight through to `templates/architecture/c4-container.md` (the template shipped in #50). Adopters who want a customised C4 shape drop their version at `<private_repo>/custom-templates/architecture/c4-container.md`. See `templates/README.md` for the path-mirroring convention. When the operator picked a non-conventional template in step 5.6 (the `[3] Other` option), `$CONTAINER_TEMPLATE` carries that choice and is used verbatim here.

Start from the resolved template. Replace:

- `{Project Name}` → the project's real name (from the handover)
- The sample `System_Boundary` contents → the containers you detected
- The sample `Rel(...)` edges → a reasonable first pass:
  - `user → web` (HTTPS) if there's a `web`
  - `web → api` (HTTPS / JSON) if there's both
  - `api → db` (SQL or driver-specific) if there's a `db`
  - `api → cache` (TCP) if there's a `cache`
  - `api → worker` (enqueue) if there's a `worker`
  - `worker → <external>` (API) for each external the worker plausibly calls
  - `api → <external>` for each external the API plausibly calls

Also replace the bottom-of-file guidance section with a brief "Handover-generated — refine me" note so the user knows this was machine-drafted. Render the following literal blockquote + Maintenance section into the target file (the content below is the exact Markdown to write):

- A blockquote starting with `> **Note**: this diagram was auto-generated by /handover on YYYY-MM-DD from repo signals (package.json, docker-compose.yml, Dockerfile, Prisma schema, .env.example). It is a **starting point** — review and refine.`
- Continue with a bulleted list inside the blockquote:
  - "Container labels and tech strings — the detector may have picked a framework version wrong"
  - "Inferred relationships — user → web assumes HTTPS; adjust if your stack uses something else"
  - "External systems — anything your team uses that isn't in package.json (e.g. infra-only dependencies, direct cloud APIs called via HTTP) won't have been detected"
- Close with: `> Update the "Maintenance" section below once the diagram is stable.`
- Then a blank line, then a second-level heading `## Maintenance`, then one line: `(From the template — update when L2 containers change.)`

#### Write path

```
projects/<name>/architecture/container.md
```

Create `projects/<name>/architecture/` if missing.

#### If there's nothing meaningful to draw

If after scanning you find zero signals (no `package.json`, no `pyproject.toml`, no Dockerfile, no known framework, no DB), skip the file and note in the summary: `architecture/container.md: skipped (no container signals detected — add manually from the C4 container template — resolve via portfolio_resolve_template architecture/c4-container.md — when ready)`. Better to write nothing than fabricate a wrong diagram.

### 6.1. Write the L1 context + sequence diagram stubs (if selected)

These are the other two **in-skill** template-backed docs from the step 5.6 catalogue (rows 2 and 7). Generate each only when it was selected; otherwise skip silently.

**Row 2 — L1 context diagram** (`projects/<name>/architecture/context.md`): render from the template chosen in the per-doc pick (`$CONTEXT_TEMPLATE`, falling back to `portfolio_resolve_template architecture/c4-context.md`). Populate the system box with the project name and the `System_Ext` actors from the externals detected in step 6's external-systems scan (auth / payments / email / storage / LLM). Same "auto-generated — refine me" note + never-overwrite rule as the container stub.

```bash
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
context_template="${CONTEXT_TEMPLATE:-$(portfolio_resolve_template architecture/c4-context.md)}"
```

**Row 7 — sequence diagram** (`projects/<name>/architecture/sequence-<flow>.md`): only meaningful when a clear request flow surfaced during the read (e.g. an auth handshake or a primary API path). Render from `$SEQUENCE_TEMPLATE` (fallback `portfolio_resolve_template architecture/sequence.md`). If no obvious flow exists, skip and note `sequence: skipped (no clear flow detected)` — don't fabricate one.

```bash
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
sequence_template="${SEQUENCE_TEMPLATE:-$(portfolio_resolve_template architecture/sequence.md)}"
```

Both follow the architecture-stub conventions: write once, never overwrite (preserve on re-handover), and prepend the machine-drafted note. The richer rows (3–6: DFD, Feature Inventory, journey, vision) are **not** generated here — they hand off to `/dfd`, `/extract-features`, `/journey`, `/tech-vision` per step 5.6's hand-off offer.

### 7. Append to the portfolio registry

**Don't just print the snippet** — offer to append it automatically:

```

Ready to add {name} to apexyard.projects.yaml? (y/n)
> y

```

If yes:

1. **Locate the registry**: `apexyard.projects.yaml` at the root of the ops repo. If missing, first copy from `apexyard.projects.yaml.example` and show the user a warning: `⚠ Registry didn't exist — created from .example. You may need to fill in other projects.`

2. **Append the entry**. Use `yq` if available for a safe YAML edit, otherwise append as plain text with careful indentation. Resolve the registry path via the helper (single-fork or split-portfolio — same code path):

   ```bash
   source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
   source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
   REGISTRY=$(portfolio_registry)

   # Prefer yq for correctness
   if command -v yq >/dev/null 2>&1; then
     yq eval -i '.projects += [{"name": "{name}", "repo": "{owner/name}", "workspace": "workspace/{name}", "docs": "projects/{name}", "status": "handover", "roles": [{roles}]}]' "$REGISTRY"
   else
     # Fallback: plain text append
     cat >> "$REGISTRY" <<'YAML'
     - name: {name}
       repo: {owner/name}
       workspace: workspace/{name}
       docs: projects/{name}
       status: handover
       roles:
         - tech-lead
         - backend-engineer
   YAML
   fi
   ```

3. **Validate the result**:

   ```bash
   # Prefer yq or python -c 'import yaml; yaml.safe_load(open(path))'
   yq eval '.' "$REGISTRY" >/dev/null 2>&1 \
     || python3 -c "import sys, yaml; yaml.safe_load(open('$REGISTRY'))" 2>&1
   ```

   If validation fails: **restore the previous version** from a backup made before the write, print the parse error, and tell the user to fix it manually. Never leave the registry in a broken state.

4. **Confirm to the user**:

   ```
   ✓ Added {name} to apexyard.projects.yaml
     status: handover
     roles: {the derived list}
   ```

If the user says `n` at the prompt, print the snippet they'd need to copy manually and continue to step 8 without writing anything:

```
Skipping the auto-append. If you want to add it later, copy this into apexyard.projects.yaml:

  - name: {name}
    repo: {owner/name}
    workspace: workspace/{name}
    docs: projects/{name}
    status: handover
    roles: {derived list}
```

### 7.5. Offer to file Next Steps as tracker tickets

The assessment's `## Next Steps` section (written in step 5) enumerates concrete follow-up work derived from the risks found. By default those entries are static prose — the operator reads them in the markdown and translates each to a `/feature` / `/task` / `/bug` invocation by hand. Recommendations rot when that translation step has friction. This step closes the loop: surface each next-step entry inline, prompt y/n per item, and dispatch the right ticket-creation skill per accepted item.

#### Pre-check: is GitHub Issues enabled on the project repo? (github tracker only — #653)

Tickets filed here land in the **project's own** repo, and GitHub disables Issues on forks/new repos by default — so this is the moment a `gh issue create` would fail with `the '<owner>/<repo>' repository has disabled issues`. Probe it first (gated on `tracker.kind` — silent no-op for linear/jira/none):

```bash
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-tracker.sh"
# <owner/repo> is the project's repo resolved in step 1 / appended in step 7.
if ! tracker_check_issues "<owner/repo>"; then
  : # warning + enable hint already printed to stderr — advisory, non-blocking
fi
```

This is **advisory** — if issues are disabled, surface the warning + the `gh repo edit <owner/repo> --enable-issues` hint and let the operator decide before the per-item filing loop (offering to enable it is fine on explicit y/n; never auto-enable). If they decline, skip the filing offer (the tickets can't be created) and note the next steps remain in the assessment markdown.

#### Skip conditions

- **Zero next-step entries** (no risks found, no synthetic "calibrate review standards" / "stakeholder sync" entries either) → skip this step silently
- **All next-step entries already carry a `Filed as #N` marker** from a prior run (re-handover with no NEW entries since the last filing pass) → skip with a one-line note: `All next steps were filed in prior runs — no new tickets offered.`. Detection: scan the regenerated `## Next Steps` list; if every entry either already-carries a `Filed as [#N](...)` link preserved through step 5's regeneration OR is a duplicate of a prior-run entry that did, skip. Mixed states (some filed, some new) do NOT skip — new entries get offered while filed-already entries are silently skipped at the per-item prompt loop (see § "Surface the entries" below).
- **Operator opted out of the registry append at step 7** (answered `n` to "Ready to add {name} to apexyard.projects.yaml?") → skip. The project isn't in the registry, so ticket-source links pointing at `projects/<name>/handover-assessment.md` won't reach a teammate context.

#### Surface the entries

Scan the regenerated `## Next Steps` list. Partition into two buckets:

- **Already-filed** — entries that carry a `Filed as [#N](...)` link from a prior step 7.5 run (preserved through step 5's regeneration; see § Next Steps "Re-handover preservation"). These are skipped silently — the operator never sees them in the prompt.
- **Unfiled** — entries with no `Filed as` link. These are the only entries surfaced.

If the unfiled bucket has zero entries, fall through to the skip-condition "All next-step entries already carry a `Filed as #N` marker" and emit the one-line note. Otherwise print the unfiled entries (top 3-5 by mapping-table order), numbered:

```
Found 5 follow-up tasks in the assessment (2 were filed in a prior run — skipping). File any as tracker tickets?

  1. /audit-deps <name> — triage the high-severity lodash CVE before any new feature work
  2. Fix the 7 failing tests in src/api/orders before merging new PRs
  3. Set up test coverage reporting (vitest coverage config) before the first feature
  4. Triage the issue backlog with the previous owner before taking ownership
  5. Write a minimum-viable README (what the project does, how to run it locally, where it deploys)

Per-item y/n (or 'all', 'none', a comma-list like '1,3,5'):
```

The leading `(N were filed in a prior run — skipping)` parenthetical only appears when at least one prior-filed entry was found and skipped; on first-handover runs, omit it.

Accept:

- `all` or `y` — file every entry
- `none` or `n` or empty input — skip all
- Comma-separated indices (e.g. `1,3,5`) — file just those
- Per-item y/n if the operator wants to walk through them one at a time — fall back to interactive if the response doesn't match the bulk shapes

If the response is ambiguous, ask one clarification question; don't loop indefinitely. Default to skip-all on a second ambiguous answer.

#### Route each accepted item to the right skill (heuristic)

For each accepted entry, classify by shape + dispatch the matching ticket-creation skill:

| Entry shape | Skill | Why |
|-------------|-------|-----|
| Mentions a fix to broken behaviour ("Fix the N failing tests", "Resolve the X regression") | `/bug` | The work is to fix something measurably broken |
| Mentions triage / decision / strategy ("Triage the backlog", "`/decide` on observability") | `/task` | Investigative or decision-making work; no broken behaviour to fix |
| Mentions a new capability or scaffolding ("Set up coverage reporting", "Write a README", "Enable CI") | `/task` | Tech-debt or infra-fix; not user-facing capability so `/task` fits better than `/feature` |
| Mentions invoking another framework skill ("`/audit-deps` <name>", "`/code-review` the most-recent PR") | `/task` | The work is "run this skill against this project" — track as a task to do, not a feature to build |
| Mentions a stakeholder action ("Stakeholder sync", "Onboard role X") | `/task` | Coordination work; `/task` fits |

**Default to `/task` when in doubt.** The framework's `/feature` skill is reserved for user-facing capabilities, and handover-derived next-steps are almost never that shape. The heuristic above keeps the routing predictable rather than asking the operator to disambiguate per item.

If the operator disagrees with the auto-route (e.g. they want a specific item filed as `/feature` instead of `/task`), they can say `1 as feature` / `3 as bug` etc. inline. Honour the override; default to the heuristic when no override is given.

#### Dispatch with the assessment as the source

For each accepted item, dispatch the chosen skill with these inputs:

- **Title** pre-filled from the next-step entry — strip any leading skill-prefix (e.g. drop the `/audit-deps <name> —` lead to leave `triage the high-severity lodash CVE before any new feature work`), trim, capitalise the first letter
- **Body** pre-filled with the source line as the last paragraph:

  ```
  _Source: handover deep-dive on YYYY-MM-DD — see `projects/<name>/handover-assessment.md` in the ops fork (or in the private portfolio sibling repo for split-portfolio v2 adopters) for the assessment that surfaced this work._
  ```

  **Plain path, no markdown link.** The ticket is rendered against the TARGET repo's URL space on GitHub, but the assessment lives in the OPS FORK (or, for split-portfolio v2 adopters, the private sibling repo). A markdown link of any relative form would be dead-on-render. Naming the path as prose is honest about the cross-repo lookup the reader has to do, and survives the split-portfolio v2 case where the assessment isn't reachable from a public link at all.

- **Repo**: the just-adopted project's repo (the `repo:` field from the registry entry written in step 7)

The dispatched skills (`/task`, `/bug`, `/feature`) handle the full ticket-creation flow including the `validate-issue-structure.sh` gate + the active-issue-skill marker (per AgDR-0030).

#### Update the assessment doc post-filing

After all dispatched tickets land, rewrite the assessment's `## Next Steps` section in-place:

- Replace each prose entry that became a ticket with the ticket-link form: `1. ~~/audit-deps...~~ → Filed as [#42](https://github.com/<owner>/<repo>/issues/42)`
- Leave unfiled entries as-is (un-strikethrough, un-linked)

So a future reader of `handover-assessment.md` can see which next-steps became tickets and which are still TODO.

#### Failure handling

On the first ticket-creation failure (`validate-issue-structure.sh` exit, `gh` API error, network failure, etc.), STOP and report. Already-filed tickets stay (don't roll back); tell the operator exactly which ones did file:

```
[3/5] Filing "Triage the issue backlog with the previous owner before taking ownership"… ✗

Error from /task:
  {stderr from the dispatched skill}

Filed so far: 2 tickets (<owner>/<repo>#41, #42).
Remaining: 3 entries (not filed).

What now?
  1. Retry — re-run the same dispatch
  2. Skip — drop this entry, continue with the next 2
  3. Abort — stop here; the 2 already-filed tickets stay
```

Mirrors `/tickets-batch`'s failure-handling shape (see [`.claude/skills/tickets-batch/SKILL.md`](../tickets-batch/SKILL.md) § "Failure handling").

#### Report

Append to the step 10 summary:

```
Next-step tickets filed:   {N filed of M offered | none offered (zero risks) | declined (skipped all)}
```

If at least one was filed, also list them inline in the summary:

```
Filed follow-up tickets:
  #41 — /task — Triage lodash CVE                  — <repo URL>
  #42 — /bug  — Fix 7 failing tests in src/api/orders — <repo URL>
```

### 8. Offer follow-up deep-dive skills (against the already-cloned repo)

The repo was cloned in step 1.5-clone (or was already local). Offer follow-up deep-dive skills that benefit from the local clone + LSP tooling. This replaces the old "clone first" offer — cloning happened earlier, so this step is purely about what to run next.

#### Branching on clone status

**If `$CLONE_STATUS` is `cloned` or `preserved`:**

Print a single follow-up offer after the step 10 summary:

```
✓ <name> is cloned at $WORKSPACE_DIR/<name>/ and indexed in MCP.
  Want to run any of the following against the clone now?

  1. /threat-model <name>   — STRIDE threat model (recommended for first handover)
  2. /security-review <name> — Security Auditor pass on the codebase
  3. /code-review <name>    — Rex code-quality review

  Note: LSP-aware navigation requires ENABLE_LSP_TOOL=1 and a per-language
  Claude Code LSP plugin installed. Cross-project queries still need grep
  (LSP is per-workspace). Cold-start on large monorepos can be 30+ seconds.

[1/2/3/all/none — default none]
```

Accept:

- `1`, `2`, `3` — run that specific skill
- `all` — run all three in sequence
- `none` or empty — skip; the operator can invoke any skill manually later

The skill never invokes follow-up skills automatically — the operator explicitly selects. On `none` / empty, continue to the final summary with no side effects.

**If `$CLONE_STATUS` is `declined`:**

Skip this step silently. The operator consciously opted out of cloning; don't re-offer.

**If `$CLONE_STATUS` is `failed: <reason>`:**

Print a brief recovery note only — don't re-attempt the clone:

```
Note: the clone of <name> failed earlier (<reason>). Once you have a local
copy at $WORKSPACE_DIR/<name>/, you can run /threat-model, /security-review,
or /code-review against it directly.
```

Then continue to the final summary.

### 8.5. Generate the in-repo `AGENTS.md` (only if row 8 was selected — default-OFF)

This is the **only** step that writes into the **target repo**, and it does so the same way any change to that repo would: a branch + PR, reviewed by the repo owner before merge. It is a deliberate, scoped exception to Rule 1 ("read-only against the target repo") — see Rule 1's "Exception" note and AgDR-0073.

#### Selection + preconditions

- **Selection condition**: run this step only when row 8 (`In-repo AGENTS.md`) was selected in step 5.6. It is **default-OFF** — the operator must consciously tick it (or name it in the comma-list, or pass `--all`). If not selected, skip silently and note `AGENTS.md: not selected` in the summary.
- **Clone precondition**: a local clone is required to branch + PR. If `$CLONE_STATUS` is `declined` or `failed`, skip with a one-line note: `AGENTS.md: skipped (no local clone — re-run with the repo cloned into workspace/<name>/)`. The repo root is `$WORKSPACE_DIR/<name>/` (resolve via `portfolio_workspace_dir`).
- **Confirm before any target-repo write**. This is the first time `/handover` writes into the target repo, so make it explicit:

  ```
  Generate AGENTS.md for <name> and open a PR against its repo?

  This is the only step that writes into the adopted repo itself. It will:
    • create a branch (docs/agents-md) in workspace/<name>/
    • write AGENTS.md (derived from this handover's assessment)
    • {if no CLAUDE.md exists} write a one-line CLAUDE.md importing it
    • push and open a PR for the repo owner to review

  No direct commit to the default branch. Existing AGENTS.md / CLAUDE.md
  are PRESERVED (never overwritten).

  Proceed? [y/N — default N]
  ```

  Default **N**. On anything other than an explicit yes, skip and note `AGENTS.md: declined` in the summary.

#### Never-overwrite check (preserve, like the architecture stubs)

Before writing anything, check the target repo's working tree:

```bash
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
WORKSPACE_DIR=$(portfolio_workspace_dir)
REPO="$WORKSPACE_DIR/<name>"

AGENTS_EXISTS=no; [ -f "$REPO/AGENTS.md" ] && AGENTS_EXISTS=yes
CLAUDE_EXISTS=no; [ -f "$REPO/CLAUDE.md" ] && CLAUDE_EXISTS=yes
```

- If `AGENTS.md` already exists → **do not write it, do not open a PR**. Note `AGENTS.md: preserved (already present in repo)` and skip the rest of this step. A human-maintained operating manual always wins (Rule 21). Refresh is manual: the operator deletes the file and re-runs.
- If `AGENTS.md` is absent but `CLAUDE.md` exists → write `AGENTS.md` only; do **not** touch the existing `CLAUDE.md` (preserve it).
- If both are absent → write `AGENTS.md` **and** a one-line `CLAUDE.md` that imports it.

#### Compose `AGENTS.md` from the live assessment (NOT a generic template)

Derive the content from what this handover already discovered (steps 2–5). Keep it focused on **stable** information — the things an agent needs to start working and that don't change every commit (commands, layout, conventions). Leave the volatile risk/integration analysis in `handover-assessment.md` (the role-split — see Rule 22). Use this shape:

````markdown
# AGENTS.md

> Generated by apexyard `/handover` on YYYY-MM-DD — review & refine. Keep this file focused on stable operating info (commands, layout, conventions); it is the operating manual for any agent (Claude Code, Cursor, Codex, …) working in this repo.

## What this is

{One or two sentences: what the project is, derived from README + step 3 tech-stack detection.}

## Tech stack

- Language / runtime: {from step 3}
- Framework: {from step 3}
- Database: {from step 3, if any}
- Test framework: {from step 3}

## Commands

{Real commands discovered in step 3 (package.json scripts / Makefile / pyproject) and verified in step 4 where a build was attempted. Do NOT invent commands — list only what the repo actually defines. Mark unverified ones.}

```bash
# install
{e.g. npm install}
# build
{e.g. npm run build}
# test
{e.g. npm test}
# lint
{e.g. npm run lint}
# run / dev
{e.g. npm run dev}
```

## Project layout

{The top-level tree from step 2, annotated with what each dir holds where known. Keep it short — the load-bearing dirs, not an exhaustive listing.}

## Conventions

{Type-safety / module-boundary / lint conventions from the step 4.5 harnessability scan, stated as "how code is expected to look here" — e.g. "TypeScript strict mode is on; keep new code strict-clean", "ESLint runs in CI; run `npm run lint` before pushing".}

## Gotchas

{The key gotchas/risks from step 5 that an agent needs to know up front — stated as operating cautions, not the full risk register. For LOW-harnessability repos, surface what's fragile or missing explicitly, e.g. "No coverage threshold configured — tests may pass with low coverage", "No lint baseline — style is inconsistent across the codebase". Honesty over polish.}
````

For **low-harnessability** repos (step 4.5 verdict `low`), the Conventions + Gotchas sections MUST surface what's fragile/missing (no strict types, no lint baseline, no coverage signal) rather than implying a maturity the repo doesn't have. This is the in-repo echo of the assessment's LOW warning — agents working in the repo need to know the guardrails aren't there.

#### Write, branch, and open the PR

All of this happens inside the target repo clone (`$REPO`), on a dedicated branch — never the default branch:

```bash
cd "$REPO"
DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@')
DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}
git checkout -b docs/agents-md "origin/$DEFAULT_BRANCH" 2>/dev/null || git checkout -b docs/agents-md

# Write the composed AGENTS.md (Write tool) to "$REPO/AGENTS.md".
# If both AGENTS.md and CLAUDE.md were absent, also write the one-line shim:
#   echo '@AGENTS.md' > "$REPO/CLAUDE.md"
# (a CLAUDE.md whose entire content is the @AGENTS.md import — canonical content
#  lives in AGENTS.md; CLAUDE.md just pulls it in for Claude Code.)

git add AGENTS.md   # plus CLAUDE.md only if it was newly created — add SPECIFIC files, never -A
[ "$CLAUDE_EXISTS" = no ] && [ -f CLAUDE.md ] && git add CLAUDE.md
git commit -m "docs: add AGENTS.md operating manual (generated by apexyard /handover)"
git push -u origin docs/agents-md
gh pr create --base "$DEFAULT_BRANCH" --head docs/agents-md \
  --title "docs: add AGENTS.md operating manual" \
  --body-file <(cat <<'BODY'
## Summary
- Adds an `AGENTS.md` operating manual generated by apexyard `/handover` from a deep read of this repo (build/test/run commands, layout, conventions, gotchas).
- `AGENTS.md` is the canonical, tool-agnostic file; any agent (Claude Code, Cursor, Codex, …) auto-loads it on entry, so build commands / layout / gotchas don't have to be re-discovered each session.
- {If a CLAUDE.md shim was added:} Adds a one-line `CLAUDE.md` that imports it (`@AGENTS.md`) so Claude Code picks it up without duplicating content.

## Testing
- Open `AGENTS.md` and confirm the commands match how you actually build/test/run this repo; refine anything the static read got wrong.

_Generated by apexyard `/handover` — review & refine._
BODY
)
```

Notes:

- **Specific-file staging only** — `git add AGENTS.md` (and `CLAUDE.md` only when newly created). Never `git add -A` / `git add .`.
- **Branch + PR, never a direct commit to the default branch.** The repo owner reviews before merge — `/handover` does not merge the PR.
- This PR lives in the **target repo's** tracker/SDLC, not the ops fork's. The ops-fork merge gates (Rex/CEO markers) don't apply — this is the target repo's own review.
- On `gh pr create` failure (issues disabled, no push rights, etc.): report the error and the branch name, leave the local branch in place, and continue to step 9. Do not retry.

#### Record for the summary

```bash
AGENTS_MD_STATUS="PR opened: <url>"   # or "preserved" | "declined" | "not selected" | "skipped (no clone)" | "failed: <reason>"
```

### 8.6. Offer the "Governed by ApexYard" badge (only if row 9 was selected — default-OFF)

Every repo apexyard governs is a potential backlink + a visible signal that the repo follows a real SDLC — but nothing in `/handover`'s output today surfaces that fact on the adopted repo itself. This step closes that gap the same way step 8.5 closes the "agent operating manual" gap: an opt-in, PR-delivered write into the **target repo**, never a direct commit. See AgDR-0090.

#### Selection + preconditions

- **Selection condition**: run this step only when row 9 (`"Governed by ApexYard" badge`) was selected in step 5.6. It is **default-OFF** — the operator must consciously tick it (or name it in the comma-list). If not selected, skip silently and note `Badge: not selected` in the summary.
- **Clone precondition**: a local clone is required to branch + PR. If `$CLONE_STATUS` is `declined` or `failed`, skip with a one-line note: `Badge: skipped (no local clone — re-run with the repo cloned into workspace/<name>/)`. The repo root is `$WORKSPACE_DIR/<name>/` (resolve via `portfolio_workspace_dir`).
- **Confirm before any target-repo write.** Editing a third-party repo's README is externally visible and easy to regret — ask explicitly, every run, default No:

  ```
  Add a "Governed by ApexYard" badge to <name>'s README?

  This inserts one badge line near the top of the README, on a new branch,
  and opens a PR for the repo owner to review. No direct commit.

    [![Governed by ApexYard](https://img.shields.io/badge/governed_by-ApexYard-2F6DF6?style=flat-square)](https://github.com/me2resh/apexyard)

  Add this badge to <name>'s README? [y/N — default N]
  ```

  Default **N**. On anything other than an explicit yes, skip and note `Badge: declined` in the summary.

#### Pick the variant (governed_by vs built_with)

On a yes, offer the second badge variant for repos that were built with apexyard from the start rather than adopted into its governance after the fact:

```
Which wording fits <name>?

  [1] Governed by ApexYard   (adopted into apexyard's SDLC — the /handover case)
  [2] Built with ApexYard    (built with apexyard from the start)

[1/2 — default 1]
```

Record the pick as `$BADGE_VARIANT` (`governed_by` or `built_with`). The two canonical badge snippets — use these verbatim, never re-derive the URL by hand:

```markdown
[![Governed by ApexYard](https://img.shields.io/badge/governed_by-ApexYard-2F6DF6?style=flat-square)](https://github.com/me2resh/apexyard)
```

```markdown
[![Built with ApexYard](https://img.shields.io/badge/built_with-ApexYard-2F6DF6?style=flat-square)](https://github.com/me2resh/apexyard)
```

Brand blue `#2F6DF6`, `flat-square` style — keep both fixed; don't invent a third variant or a different color/style on your own initiative.

#### Idempotency check (never double-add)

Before writing anything, scan the target repo's README for either badge already present:

```bash
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
WORKSPACE_DIR=$(portfolio_workspace_dir)
REPO="$WORKSPACE_DIR/<name>"

README_FILE=$(ls "$REPO"/README.md "$REPO"/README.MD "$REPO"/Readme.md "$REPO"/README 2>/dev/null | head -1)

if [ -z "$README_FILE" ]; then
  BADGE_STATUS="skipped (no README found in target repo)"
elif grep -qiE 'img\.shields\.io/badge/(governed_by|built_with)-apexyard' "$README_FILE"; then
  BADGE_STATUS="skipped (badge already present in README)"
fi
```

- **No README found** → skip; note `Badge: skipped (no README found)`. Don't create one just to hold a badge.
- **Badge already present (either variant)** → skip; note `Badge: skipped (already present)`. Never add a second badge or swap the existing variant — a human who wants to change variants edits the README directly.
- Otherwise, proceed to insertion.

#### Insert near the top of the README (idempotent, one line)

Insert the chosen badge markdown directly below the first top-level heading (`# Title`) in the README — the conventional badge position. If the README has no top-level heading, insert as the first line of the file.

```bash
cd "$REPO" || exit 1
awk -v badge="$BADGE_MARKDOWN" '
  NR==1 && /^# / { print; print ""; print badge; inserted=1; next }
  { print }
  END { if (!inserted) print badge }
' "$README_FILE" > "$README_FILE.tmp" && mv "$README_FILE.tmp" "$README_FILE"
```

(`$BADGE_MARKDOWN` is the exact snippet for `$BADGE_VARIANT` chosen above, passed in verbatim — do not reconstruct it inline in the `awk` script.)

#### Write, branch, and open the PR

Mirrors step 8.5's delivery mechanics. If step 8.5 already opened (or is about to open) a PR on `docs/agents-md` in this same run, prefer adding the badge commit onto that same branch/PR instead of opening a second trivial PR — ask once: `Add the badge to the same AGENTS.md PR (branch docs/agents-md), or open a separate PR? [same/separate — default same]`. Otherwise (no AGENTS.md PR this run), open a dedicated branch:

```bash
cd "$REPO" || exit 1
DEFAULT_BRANCH=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's@^origin/@@')
DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}
git checkout -b docs/apexyard-badge "origin/$DEFAULT_BRANCH" 2>/dev/null || git checkout -b docs/apexyard-badge

git add "$README_FILE"   # specific file, never -A / -.
git commit -m "docs: add Governed-by-ApexYard badge to README"
git push -u origin docs/apexyard-badge
gh pr create --base "$DEFAULT_BRANCH" --head docs/apexyard-badge \
  --title "docs: add Governed-by-ApexYard badge" \
  --body-file <(cat <<'BODY'
## Summary
- Adds a "Governed by ApexYard" badge near the top of the README, linking back to `https://github.com/me2resh/apexyard` — a visible signal that this repo follows apexyard's SDLC (offered opt-in during `/handover`, not auto-applied).

## Testing
- Confirm the badge renders correctly and the wording (`Governed by` vs `Built with`) matches how this repo actually uses apexyard.

_Generated by apexyard `/handover` — review & refine or close if you'd rather not carry the badge._
BODY
)
```

Notes:

- **Specific-file staging only** — `git add "$README_FILE"`. Never `git add -A` / `git add .`.
- **Branch + PR, never a direct commit to the default branch.** The repo owner reviews before merge — `/handover` does not merge the PR.
- This PR lives in the **target repo's** tracker/SDLC, not the ops fork's. The ops-fork merge gates (Rex/CEO markers) don't apply.
- On `gh pr create` failure (issues disabled, no push rights, etc.): report the error and the branch name, leave the local branch in place, and continue to step 9. Do not retry.

#### Record for the summary

```bash
BADGE_STATUS="PR opened: <url> (<variant>)"   # or "preserved (already present)" | "declined" | "not selected" | "skipped (no clone)" | "skipped (no README)" | "failed: <reason>"
```

### 9. Offer validation (conditional, default-no)

If the project looks **dormant** by the heuristic — last commit > 90 days ago AND zero open PRs AND no recent issue activity (rough thresholds, the skill can probe `gh repo view` + `gh pr list` + `gh issue list` to compute) — ask:

```
This project looks dormant — run /validate-idea {name} to confirm it's
still worth investing in? y/n (default n)
```

If the user accepts, hand off to `/validate-idea {name}` (which reads the just-written `handover-assessment.md` as starting context and writes its output to `projects/{name}/validation/handover-validation.md`).

If the project is healthy (recent commits, active PRs/issues), skip the prompt entirely. Don't ask "should I validate?" on every handover — only when the dormancy signal warrants it.

### 10. Return a summary

```
Handover assessment written: projects/{name}/handover-assessment.md
Document selection:          {"checklist — generated: {list}; deferred (handed off): {list}" | "--all (full set)" | "none (assessment only)"}
Architecture stub:           projects/{name}/architecture/container.md ({written | preserved | skipped | skipped (deselected)})
In-repo AGENTS.md:           {PR opened: <url> | preserved (already present) | declined | not selected | skipped (no clone) | failed: <reason>}
Governed-by-ApexYard badge:  {PR opened: <url> (<variant>) | skipped (already present) | declined | not selected | skipped (no clone) | skipped (no README) | failed: <reason>}
Topology bundle:             {"<name>@<version> instantiated (handbooks + AgDR draft + CI pipelines)" | "declined" | "skipped (no pick)" | "pipelines pending — workspace not cloned"}
Registry updated:            apexyard.projects.yaml ({added | skipped})
Next-step tickets filed:     {N filed of M offered | none offered (zero risks) | declined (skipped all) | skipped (registry not appended)}
Workspace clone:             workspace/{name}/ ({cloned at step 1.5 | preserved (already existed) | declined (--no-clone) | failed: <reason> | n/a (local path given)})
Harness:                     {"Claude Code (native)" | "<harness list> — install command(s) printed, see docs/harnesses/<harness>.md" | "other / not sure — no adapter yet"}
Validation:                  {"completed — verdict <GREEN|YELLOW|RED>" | "skipped" | "not offered (project is active)"}

Tech stack: {one-liner}
Build: {ok / failed}
Risks: {N items} ({highest severity})
Roles activated: {comma-separated}
Top 3 next steps (still TODO after step 7.5):
  1. {first dynamic step}
  2. {second dynamic step}
  3. {third dynamic step}

{If next-step tickets were filed, append this block:}
Filed follow-up tickets:
  #41 — /task — Triage lodash CVE                  — <repo URL>
  #42 — /bug  — Fix 7 failing tests in src/api/orders — <repo URL>
  ...
```

## Rules

1. **Read-only against the target repo** — never modify the target repo without explicit permission. (The ops repo IS modified — you append to the registry and create the assessment file — but that's the point.)

   **Exceptions (explicit, opt-in, PR-delivered): in-repo `AGENTS.md` generation and the "Governed by ApexYard" README badge.** Steps 8.5 and 8.6 are the only two sanctioned writes into the target repo. Both are **opt-in and default-OFF** (rows 8 and 9 of the step 5.6 checklist), each requires an explicit per-run confirmation, and each is delivered via a **branch + PR** the repo owner reviews — never a direct commit to the default branch, and never via the ops-fork bootstrap-exempt write path. With both rows left unticked (the default), this rule holds unchanged: `/handover` writes nothing into the target repo. See step 8.5, step 8.6, Rules 21–23, AgDR-0073, and AgDR-0090.
2. **Honest assessment** — if a build fails, say so. Don't paper over problems.
3. **Always seed `projects/<name>/`** — even if minimal.
4. **Auto-append to the registry** (with confirmation) — don't leave the user to copy-paste a snippet. Propose the append, validate the resulting YAML, roll back on failure.
5. **Derive roles from the stack** — don't hard-code `[tech-lead, backend-engineer]`. The roles list depends on the actual tech stack, CI config, and security surface detected in step 3.
6. **Derive next steps from the risks** — don't emit generic placeholders. Every "Next Step" must correspond to a specific finding from the Quality Risks section of the assessment.
7. **Clone immediately when a URL is given** — when the operator provides a Git URL in step 1, clone it into `workspace/<name>/` in step 1.5-clone without asking (default-yes). The only opt-out is an explicit `--no-clone` flag on the skill invocation. When only a local path is given, use it directly — no clone needed. The old "offer the clone at the end (step 8)" pattern is gone; cloning first makes every subsequent read cheaper.
8. **Never store secrets** — if `.env` is found, list its presence but never read its contents.
9. **Status starts at `handover`** — moves to `active` only after the integration plan is executed.
10. **Never break the registry** — if the YAML append breaks the file, restore the previous version and ask the user to edit manually.
11. **Never overwrite the architecture stub** — `projects/<name>/architecture/container.md` is written once on first handover, then owned by the team. Re-runs of `/handover` (e.g. if the tech stack changed) must preserve any manual refinements. If you want to regenerate, the user deletes the file first.
12. **Architecture stubs are starting points, not truths** — the auto-generated note at the top of the file explicitly tells the user to review and refine. Never claim the detector is authoritative.
13. **Topology instantiation never overwrites** — step 5.5 copies files with `rsync --ignore-existing` / `cp -n`. Adopters who edited a topology handbook keep their edits across re-runs. Drift detection lives in `/update` (see AgDR-0048).
14. **Default is no topology** — pick 4 (Skip / custom) is the default. The pre-topology flow is byte-for-byte preserved for adopters who don't want a bundle. Never auto-pick a topology based on tech-stack detection in v1 — let the operator choose.
15. **Next-step tickets are opt-in, never auto-filed** — step 7.5 always prompts the operator before any `gh issue create`. Bulk shapes (`all` / `none` / comma-list) are conveniences, not defaults. `none` and empty input are equivalent — skip-all is the safe default if the operator's intent is unclear.
16. **The routing heuristic is the default, not the law** — step 7.5's auto-route from next-step shape to `/feature` / `/task` / `/bug` is a sensible default. The operator can override per item (`1 as feature` / `3 as bug`). When in doubt, default to `/task` — handover-derived next-steps are almost never user-facing capabilities (`/feature` shape) and rarely strictly broken behaviour (`/bug` shape).
17. **Source-link every filed ticket back to the assessment** — each ticket dispatched in step 7.5 carries a `_Source: handover deep-dive on YYYY-MM-DD — see projects/<name>/handover-assessment.md_` footer. Without that link, the assessment's context (risks, harnessability score, build status) is invisible to anyone working the ticket later, and the recommendation traceability rot is exactly the failure mode this step exists to prevent.
18. **Re-runs surface deltas, not redundancy** — the filed-marker presence on each next-step entry is the source of truth for "already done". On re-handover, step 5's regeneration of `## Next Steps` MUST preserve any `~~strikethrough~~ → Filed as [#N](url)` markers from prior runs (don't blow away the operator's filing history). Step 7.5 then prompts only on the entries that lack a `Filed as` link, so the operator never re-sees what they've already filed. If every entry already carries a `Filed as` link, the whole step skips (see § Skip conditions). Byte-equivalence of the section text is NOT the test — only the per-entry marker presence is.
19. **Document selection is a checklist, not a fixed pipeline** — step 5.6 presents the generatable artefacts as an opt-in checklist (default-ticked: the L2 container diagram). The handover assessment + harnessability score are ALWAYS written and never appear in the checklist — they are the skill's core output. `--all` is the non-interactive escape that generates the full default set with conventional templates (byte-for-byte the pre-checklist behaviour); `--interactive` (the default) presents the checklist. Distinguish computed/toggle-only rows (no template to pick) from template-backed rows (per-doc template pick).
20. **Per-doc template pick defaults to the conventional template** — for each selected template-backed doc, list the resolved candidates (framework `templates/**` + adopter `custom-templates/**` via `portfolio_resolve_template`) and default to the conventional one (candidate `[1]`, i.e. the path `portfolio_resolve_template` would pick unprompted). Empty input takes the default, keeping `--all` and "default" runs byte-stable. Only list the adopter override candidate when it actually exists. Never reimplement a dedicated skill's artefact — DFD / Feature Inventory / journey / vision hand off to `/dfd` / `/extract-features` / `/journey` / `/tech-vision`.
21. **`AGENTS.md` is opt-in, PR-delivered, and never overwrites** — the in-repo `AGENTS.md` (step 8.5) is the only artefact written into the target repo, and it is **default-OFF** so Rule 1 holds unless the operator opts in. It is delivered via a branch + PR (never a direct commit to the default branch; never via the ops-fork bootstrap-exempt path). An existing `AGENTS.md` or `CLAUDE.md` is **preserved, never overwritten** — exactly like the architecture stubs (Rule 11). `AGENTS.md` is canonical; a one-line `CLAUDE.md` importing it (`@AGENTS.md`) is offered only when no `CLAUDE.md` exists. The file carries a "generated by `/handover` on `<date>` — review & refine" note and stays focused on stable info (commands, layout, conventions). Refresh is manual (delete + re-run). See AgDR-0073.
22. **`AGENTS.md` and `handover-assessment.md` don't duplicate — they split by reader** — `handover-assessment.md` (ops fork) is the **operator's** full analysis: risks, harnessability verdict, integration plan, next-step tickets. `AGENTS.md` (in the target repo) is the **agent's** concise operating manual: stable commands, layout, conventions, and the up-front gotchas an agent needs to start working. The volatile risk/integration analysis stays in the assessment; it is not copied into `AGENTS.md`. For low-harnessability repos, `AGENTS.md`'s Gotchas section surfaces what's fragile/missing (no strict types, no lint baseline, no coverage signal) — the in-repo echo of the assessment's LOW warning.
23. **The "Governed by ApexYard" badge (step 8.6) is opt-in, PR-delivered, idempotent, and never a default** — row 9 of the step 5.6 checklist is **default-OFF** in every mode (checklist default, `--all`, and interactive `all`); it is only generated when explicitly ticked or comma-listed. Every run confirms with the operator by name (`Add a "Governed by ApexYard" badge to <name>'s README?`) before touching the target repo — there is no silent or bulk-implied consent for an externally-visible README edit. The badge is delivered via a branch + PR exactly like `AGENTS.md` (never a direct commit). It is **idempotent**: if either badge variant (`governed_by` or `built_with`) is already present in the README, the step skips and reports `already present` rather than adding a duplicate or swapping variants. The badge markdown itself (URL, color `#2F6DF6`, `flat-square` style) is fixed and quoted verbatim in step 8.6 — don't re-derive it. See AgDR-0090.
24. **`docs/harnesses/README.md` is the single source of truth for harness support — step 1.6 summarises and links it, never duplicates the matrix.** Read the doc fresh when printing a harness's install command, precondition, or tier rather than trusting a stale table baked into this skill. Never round a harness's tier up — Cursor is failClosed-only, not live-proven, and the skill says so verbatim. Step 1.6 is informational only: it prints the adapter install command but never runs it against the target repo.

## When to use this

| Trigger | Use `/handover`? |
|---------|------------------|
| Inherited a codebase from another team | Yes |
| Acquired a company's repo | Yes |
| Adopted an open-source project as a dependency | No — that's `/audit-deps` |
| Forked an internal tool you wrote yesterday | No — it's already yours |
| Importing a side project into the org | Yes |

---

*Part of [ApexYard](https://github.com/me2resh/apexyard) — multi-project SDLC framework for Claude Code · MIT.*

---

Source: https://www.openparable.com/skill/productivity/handover (OpenParable). Cite the canonical URL above.
