| name | handover |
| description | Onboard an external repo via a structured handover assessment + harnessability scoring across 5 codebase dimensions. |
| argument-hint | <project name> [path or url] [--topology <name>] [--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)
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:
| 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):
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"
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"
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.
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:
find <repo> -maxdepth 2 -type d \
! -path '*/node_modules*' \
! -path '*/.git*' \
! -path '*/dist*' \
! -path '*/build*'
ls <repo>/README* <repo>/package.json <repo>/pyproject.toml \
<repo>/Cargo.toml <repo>/go.mod <repo>/Gemfile 2>/dev/null
ls <repo>/.github/workflows/ 2>/dev/null
git -C <repo> log -1 --format='%h %ai %an %s'
git -C <repo> shortlog -sn --no-merges | head -10
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, dependenciespyproject.toml / requirements.txt → PythonCargo.toml → Rustgo.mod → GoGemfile → RubyDockerfile → 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:
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"
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.
| # | 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 rowsall — 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"
default_tpl=$(portfolio_resolve_template architecture/c4-container.md)
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
SELECTED_DOCS="container,dfd,feature-inventory"
CONTAINER_TEMPLATE="$default_tpl"
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:
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
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 webweb → api (HTTPS / JSON) if there's bothapi → db (SQL or driver-specific) if there's a dbapi → cache (TCP) if there's a cacheapi → worker (enqueue) if there's a workerworker → <external> (API) for each external the worker plausibly callsapi → <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:
-
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.
-
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)
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
cat >> "$REGISTRY" <<'YAML'
- name: {name}
repo: {owner/name}
workspace: workspace/{name}
docs: projects/{name}
status: handover
roles:
- tech-lead
- backend-engineer
YAML
fi
-
Validate the result:
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.
-
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):
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-tracker.sh"
if ! tracker_check_issues "<owner/repo>"; then
:
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 entrynone 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 ", "/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 § "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 skillall — run all three in sequencenone 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:
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:
# 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:
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
git add AGENTS.md
[ "$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'
- 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.
