User Story

As an adopter onboarding a new project to ApexYard, I want to pick a topology template ("TypeScript NextJS web app", "Python FastAPI service", "Go data pipeline", etc.) and have ApexYard pre-bundle the right handbooks + AgDR templates + CI pipeline + Rex domain knowledge for that shape, so that adopters don't reassemble the same governance surface from scratch on every onboarding.

Acceptance Criteria

• New topologies/ directory at the framework root, with subdirs per topology shape (e.g. topologies/typescript-nextjs/, topologies/python-fastapi/, topologies/go-data-pipeline/)
• Each topology dir bundles: curated handbooks/architecture/*.md subset, handbooks/language/<lang>/*.md, handbooks/domain/* if applicable, golden-paths/pipelines/*.yml for the stack, templates/agdr-*-<stack>.md for stack-specific decisions
• /handover extended to ask "which topology?" early in the flow; defaults to "skip / custom"
• On topology pick, /handover instantiates the bundle into the project's handbooks/, copies the pipeline into .github/workflows/, seeds the AgDR templates into docs/agdr/ (as drafts, not commits)
• Each topology ships with at least 3 concrete handbooks/domain/<area>/*.md files demonstrating the paths: frontmatter convention from [Feature] Rex domain-aware code review — handbooks/domain/<area>/ glob with diff-match loading + lessons-learned capture #293
• Version-tracking: each topology dir has a VERSION file so /update can detect when an adopter's instantiated bundle is behind the upstream framework's topology
• AgDR documents the design choice (path-mirroring vs frontmatter-registry vs config-block)

Design Notes

This is the natural next big move once #293 (domain handbooks) lands. The pieces exist scattered today — golden-paths/pipelines/, handbooks/, roles/, /handover — but adopters assemble them by hand on every new project. Bundling them per-topology is what industry harness-engineering calls harness templates: "a bundle of guides and sensors that leash a coding agent to the structure, conventions and tech stack of a topology."

Ashby's Law angle: committing to a topology narrows the variety the harness has to regulate, which makes a comprehensive harness more achievable.

Risk: version drift. As soon as an adopter instantiates a topology, it falls out of sync with upstream improvements. Same problem service templates have had for years. Mitigation: /update detects topology version and offers to re-instantiate (operator-approved diff per file).

Risk: topology proliferation. If we ship 50 topologies, none get maintained well. Mitigation: start with 3 (TS NextJS, Python FastAPI, Go data pipeline) and only add when 5+ adopters request a new one.

Out of Scope

• Adopter-authored topologies (could come in v2.1; v2.0 is framework-curated only)
• Per-team topology overrides
• Topology composition (e.g. "NextJS web + Python ML service" — handle as two separate registries first)

Glossary

Surfaced 2026-05-19 reading industry harness-engineering article. v2.0 candidate — not in v1.5.