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

Architecture

In plain English: ApexYard stores the rules, tools, and history for each product you manage. The diagram below shows the five layers that make that work — useful if you want the technical detail; you do not need it to start. If you'd rather see a day with it, read how it works.

What ApexYard is 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 ApexYard does One ops fork holds the registry, hooks, rules, skills, agents, templates, and handbooks; managed projects clone in as gitignored workspace dirs. What you need to start Fork apexyard, register your projects, and read this page if you are 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/ · 60 shell gates Merge gate · ticket-first · secrets · … [=] Rules .claude/rules/ · 18 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/ · 66 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 do not 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 defines the registry and the controls that must run. Capability defines the skills and agents that perform the work. Framework defaults provide reusable templates and handbooks. Customisation adds adopter-specific rules and workflows. Per-project data records the projects governed by the fork.

Customisation overlay

The framework ships defaults. custom-templates/, custom-skills/, and custom-handbooks/ let you adapt the workflow without editing the framework files.

Path mirroring is the convention. Put an override at the same relative path as the framework default and the custom version takes precedence.

How does the portfolio model work?

One fork, every project

Fork ApexYard once and use the fork as your operations repository. Each governed project 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. Each is a real clone of the managed repository with its own branches, pull requests, and CI.

Optional private sibling repo

The dashed box on the right is optional. Put the registry, onboarding, projects/, workspace/, and custom-* trees in a private sibling repository when portfolio names must stay private. Skills resolve these paths via the portfolio.* keys in .claude/project-config.json. Full setup walkthrough lives in docs/multi-project.md ↗.

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

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