~/apexyard · architecture
apexyard / architecture 5 layers, optional sibling repo

Architecture

In plain English: ApexYard is one place that holds the rules, the tools, and the history for every product you build. The diagram below shows the five layers that make that work — useful if you want the technical detail; you don't need it to start. If you'd rather see a day with it, read how it works.

What is it? ApexYard governs a portfolio of repos as one organisation: 5 layers (governance, capability, framework defaults, customisation overlay, per-project data) plus an optional split-portfolio private-sibling repo. What can it do? One ops fork holds the registry, hooks, rules, skills, agents, templates, and handbooks; managed projects clone in as gitignored workspace dirs. What's needed to start? Fork apexyard, register your projects, and read this page if you're deciding how to lay out the fork for your team. The diagram below is the canonical mental model.

See also: overview · skills · setup guide ↗

[#] ApexYard Ops Fork (your-org/apexyard — the public fork you clone) GOVERNANCE — declares what, enforces how [*] Registry apexyard.projects.yaml Lists every managed project [~] Hooks .claude/hooks/ · 39 shell gates Merge gate · ticket-first · secrets · … [=] Rules .claude/rules/ · 11 files Self-discipline guides for the agent [i] Onboarding onboarding.yaml Company name, mission, team, stack CAPABILITY — what the agent can do [/] Skills .claude/skills/ · 59 slash commands /feature /handover /c4 /threat-model /process /dfd /journey /update /release … [>] Agents .claude/agents/ · 23 specialised sub-agents Rex (code review) · Hakim (security) · Munir (deps) · Tariq (PR) · Idris (tickets) FRAMEWORK DEFAULTS — ship out of the box [T] templates/ PRD · AgDR · technical-design · C4 context/container · DFD · vision · spike · … Overridable per file via custom-templates/<same-path>.md [H] handbooks/ architecture/ · general/ · language/<lang>/ ← Rex consults during code review Additive: custom-handbooks/<path> layered alongside, NOT replacing CUSTOMISATION LAYER — adopter overrides [+] custom-templates/ Path-mirror override Wins over framework on collision (#244) [+] custom-skills/ Symlinked into .claude/skills/ Framework moves to .framework.bak (#243) [+] custom-handbooks/ Additive — Rex reads BOTH layers Same path conventions as framework (#243) overrides layers onto PER-PROJECT DATA — one entry per row in the registry [d] projects/<name>/ Committed to the fork — ApexYard's view of each project README.md · roadmap.md · handover-assessment.md prds/ · architecture/ (C4, DFD, vision) · journeys/ processes/ (BPMN) · feature-inventory.md · audits/ · updates/ docs/agdr/ ← per-project Agent Decision Records "Would it follow the code if the project spun out tomorrow?" NO → here. [w] workspace/<name>/ Live git clones — gitignored from the fork itself Real git clone of the managed repo cd into to do code work · branches · PRs · CI LSP-aware skills run here (semantic index) Cross-repo trace (/process, /dfd) follows registry links "Would it follow the code if the project spun out tomorrow?" YES → here. [lock] Sibling Private Repo Optional — split-portfolio v2 mode For adopters on GitHub Free who don't want portfolio names on a public repo. Resolved via portfolio.* keys in .claude/project-config.json CONTENTS — replaces public-fork copies [*] apexyard.projects.yaml [i] onboarding.yaml [d] projects/ [w] workspace/ [+] custom-templates/ [+] custom-skills/ [+] custom-handbooks/ When v2 is enabled, skills resolve these paths transparently — the public fork stays slim, your private data never leaks upstream. PUBLIC FORK MARKER [anchor] .apexyard-fork (presence marker) walked-up by hooks to find the ops-fork root resolves into fork

What is the ApexYard architecture?

The 5-layer model

Governance declares what's true (registry, onboarding) and what's enforced (hooks, rules). Capability is what the agent can DO — skills + sub-agents. Framework defaults ship with the fork: templates and handbooks. Customisation is your overrides; the red border in the diagram is the override semantic. Per-project data lives at the bottom — one entry per row in the registry.

Customisation overlay

The framework ships defaults; custom-templates/, custom-skills/, and custom-handbooks/ let you override them per file (templates), add proprietary slash commands (skills), or layer company-confidential coding standards alongside the public ones (handbooks).

Path-mirroring is the convention — drop your version at the same relative path as the framework default, and it wins on collision.

How does the portfolio model work?

One fork, every project

You fork ApexYard once and treat the fork as your ops repo. Every project you want governed gets a row in apexyard.projects.yaml and a folder under projects/<name>/. Skills like /inbox, /status, and /tasks aggregate across the registry — one command surveys the whole portfolio.

Live working copies (workspace/<name>/) are gitignored from the fork itself; each is a real clone of the managed repo with its own branches, PRs, and CI.

Optional private sibling repo

The dashed box on the right is opt-in. Adopters on GitHub Free who don't want portfolio names on a public fork put the registry, onboarding, projects/, workspace/, and the custom-* trees in a sibling private repo. Skills resolve paths via the portfolio.* keys in .claude/project-config.json — the public fork stays slim, the private data never leaks upstream. Full setup walkthrough lives in docs/multi-project.md ↗.

Convinced this is the shape your fork needs?
Three steps and you're configured — under five minutes.

Quickstart — fork & /setup in minutes → ⑂ Fork on GitHub ↗ See a day with it →