handover

name: handover description: Onboard an external repo via a structured handover assessment + harnessability scoring across 5 codebase dimensions. argument-hint: " [path or url] [--topology ] [--all | --interactive]" allowed-tools: Bash, Read, Grep, Glob, Write

/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:

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:

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 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:

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).

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):

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

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

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

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 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.

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:

# 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

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):

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

# 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:

# {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

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

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)

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 § "Topology drift detection").

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

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)

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

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.

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.

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)

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:

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). 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

# 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)

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

Slot: api (HTTP backend)

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)

If none → omit.

Slot: db (primary relational / document store)

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

Slot: cache

Use ContainerDb(cache, ...).

Slot: queue (if distinct from worker)

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:

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.

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.

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):

   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:

   # 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.

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:

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 § "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.

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)})
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)})
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.)
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.

When to use this

Part of ApexYard — multi-project SDLC framework for Claude Code · MIT.