ApexYard

Take agent-built code the last mile — safely to production.

You built something real with AI. Then it fell apart.

The first 80% flew — a working prototype in a weekend, features landing faster than you could test them. Then the context slipped. The codebase turned into a pile nobody could review, decisions vanished into chat history, and the thing you were so close to shipping never actually made it to production.

ApexYard is the machinery that takes agent-built code the last mile. It wraps your AI coding agent in the discipline a real engineering team runs on: every change moves through a ticket, gets an independent review, and hits a merge gate that stays shut until a named human says "ship it." So the code your agent writes is actually safe to put in front of users.

Concretely, it's a multi-project ops repo: you fork it, register your projects, and govern them all as one organisation — shared memory across the portfolio, a strict SDLC, and dozens of shell hooks that enforce the rules mechanically instead of hoping everyone remembers them. Built for founders who ship alone, and for teams standing up AI-enabled squads.

Claude Code is the default driver, but the rules, hooks, and templates are plain markdown and shell. Swap the AI. Keep the forge. No SaaS. No lock-in.

Proven shipping TypeScript + AWS Lambda backends, Next.js web apps, Chrome extensions, and native Swift macOS desktop apps. The stack is process and guardrails — not a language or framework lock-in.

What makes it different

Feature	Without ApexYard	With ApexYard
Code reviews	Ad-hoc prompts	Rex agent on every PR, SHA-bound approval marker
Technical decisions	Lost in chat history	Documented as Agent Decision Records
Quality gates	Hope and pray	Shell hooks block bad commits, forged markers, unreviewed merges
Merge approval	Informal "LGTM"	Two-marker gate — Rex (code) + a named human (per-PR explicit)
Database migrations	Drop-column-on-Friday	Dedicated gate: labelled ticket + migration AgDR (rollback, downtime, consumers) required before schema edits
Architecture docs	Nobody draws them	C4 L1 + L2 Mermaid templates + /c4 skill generates stubs from a codebase
Portfolio visibility	Tab through 5 GitHubs	/inbox, /status, /tasks aggregate across a single registry file
Upstream sync	Forget for 6 months	Session-start drift banner + /update skill
Role consistency	Re-explain every session	Persistent role definitions, activation-triggered
Onboarding	Days of context-setting	/setup three-exchange config

What's inside

ApexYard is a set of plain-text primitives Claude Code reads automatically — no runtime, no service:

• 20 roles across 6 departments (engineering, product, design, security, data, architecture) that activate on triggers
• 49 shell hooks that mechanically enforce the SDLC — ticket-first edits, a two-marker merge gate, migration gates, secrets scanning, and more
• 66 slash-command skills — from /setup and /handover to /decide, /code-review, /migration, and /launch-check
• 23 sub-agents — Rex (code review), Hakim (security), Tariq (design review), plus the department personas
• 18 rule files, workflow docs, and document templates (PRD, tech design, ADR, AgDR, C4 diagrams)

Full directory tree and the complete role / hook / skill / agent breakdown → docs/whats-inside.md.

Marketing site: the site that was previously bundled here has moved to its own repo (me2resh/apexyard-site) and is deployed independently at yard.apexscript.com.

Built for Claude Code first, but opencode, pi, and Codex run the same enforcement through a small adapter (Cursor partially) — see Using another AI coding tool? below.

For AI coding agents: the repo root carries AGENTS.md — a universal entry doc for Cursor / Claude Code / Aider / Cline / pi, for harnesses that don't auto-load CLAUDE.md. Details: docs/harnesses/pi.md.

Quick Start — fork and go

ApexYard governs a portfolio of repos as one organisation. You fork apexyard, clone the fork, treat it as your "ops repo", and register every project you want under management. No .apexyard/ symlinks, no nested installs — the fork IS the ops repo.

On opencode, pi, or Codex? Steps 1–3 below are plain git / gh and work as-is. Install your tool's adapter (one command — see Using another AI coding tool?) before steps 4–6; each of those steps also shows the manual-file equivalent for when there's no /skill to run. The rules that get enforced are identical either way.

1. Star + Fork on GitHub

Visit github.com/me2resh/apexyard, Star it, then Fork it into your org. You can keep the fork named apexyard or rename to something that fits your naming convention (your-org/ops, your-org/apex, etc.).

2. Clone your fork locally

gh repo clone your-org/apexyard
cd apexyard

Or with plain git:

git clone https://github.com/your-org/apexyard.git
cd apexyard

3. Add upstream for future updates

git remote add upstream https://github.com/me2resh/apexyard.git

Later, run /update to pull the latest apexyard improvements into your fork — it previews the upstream diff, merges on a sync branch, and walks you through any per-version migrations (don't hand-merge main).

4. Configure the framework — run /setup

Run /setup in Claude Code. In three exchanges (describe your stack → review the proposed defaults → accept or tweak) it captures your company, team, tech stack, and quality bar and writes your config.

/setup

Your real config lives in onboarding.yaml, which is gitignored — it stays local and is never published. /setup copies it from the tracked onboarding.example.yaml placeholder and fills it in, so nothing private is committed. (A commit-time guard blocks a filled-in onboarding.yaml if you ever try to add it.)

No /setup on your tool? cp onboarding.example.yaml onboarding.yaml and fill in your company, stack, and quality bar by hand — the gates read the file, not the skill.

5. Register your projects — run /handover

Projects join the portfolio through a skill, not hand-edited YAML. For each repo you want under management:

/handover <repo-url-or-local-path>

/handover clones the repo, scores its "harnessability" across five dimensions, seeds its per-project docs, and registers it in apexyard.projects.yaml (creating the registry on first use). /setup also offered to register your first project back in step 4.

The registry it maintains looks like this — you rarely touch it by hand:

version: 1
projects:
  - name: example-app
    repo: your-org/example-app
    docs: projects/example-app
    status: active

Register even a single repo — the portfolio skills (/projects, /inbox, /status) work off the registry. No /handover on your tool? cp apexyard.projects.yaml.example apexyard.projects.yaml and add your repos by hand — same registry, no skill required.

6. Start working

/projects          # list every managed project + status
/inbox             # PRs, issues, comments needing your attention
/status            # git + CI snapshot per project
/decide            # make a technical decision (creates an AgDR)

The hooks fire on every git / gh command, the portfolio skills aggregate across the registry, and the Code Reviewer agent can be invoked with /code-review <pr>.

Full setup guide with directory layout, daily workflow, and FAQ: docs/multi-project.md.

Keeping a fork current — upgrade in place, when to re-fork instead, and how to preserve your portfolio data either way: docs/upgrading.md.

Using another AI coding tool?

ApexYard was built for Claude Code — that's where everything is native: the /setup, /handover, and other /… commands are Claude Code skills, a convenience layer on top of the real enforcement. But the part that actually enforces your rules is plain bash, not tied to Claude Code, so other AI coding tools can run the exact same rules through a small adapter. We only claim what we've watched work: as of 2026-07-09, three tools — opencode, pi, and Codex — are proven, meaning a real agent turn on each was stopped by the same unmodified rule. Each needs one small setting so the agent's command actually reaches the rule. Cursor is the honest exception. On any of these tools, the manual fallback is always the same plain-text config files shown in the Quick Start steps above — no skill required, just done by hand.

Tool	Enforces your rules?	Setup	Good to know
Claude Code	✅ Yes — natively. Built in; the rules fire on every command.	Nothing to install — /setup and you're done.	On Windows, use Git Bash or WSL (the rules are bash).
opencode	✅ Yes — proven. A real agent's git add -A was blocked by the same rule.	bash bin/install-opencode-adapter.sh	Run opencode with --auto so the agent's command reaches the rule.
pi	✅ Yes — proven. Same, in a real pi session.	bash bin/install-pi-adapter.sh	Run pi with -a (auto-approve). pi is deliberately bare-bones — ApexYard is the governance it leaves to you.
Codex	✅ Yes — proven. Same, in a real Codex session.	bash bin/sync-codex-adapter.sh	Codex has to trust the rules once — /hooks, a one-off flag, or a user-level install. Details: docs/codex-adapter.md.
Cursor	🟡 Partly. It blocks the command, but by failing safe when its rule-runner errors — not by running our rule. We don't count it as proven.	bash bin/install-cursor-adapter.sh	Works in the Cursor IDE, not the command-line version. Install is user-level (~/.cursor/hooks.json).

Under the hood: your rules stay one set of portable bash scripts, and every tool reads the same ones — never a separate copy that can drift out of sync. A daily, credentialed Conformance CI job re-verifies each proven harness automatically, so the claims above aren't just one-off manual checks. Full per-tool setup, limits, and how to add a new tool → docs/harnesses/README.md.

Roles, workflows & templates

ApexYard ships 20 roles across 6 departments that activate on triggers, a full SDLC (Planning → Design → Build → Review → QA → Deploy → Monitor) with a dedicated migration sub-workflow, and reusable document templates (PRD, technical design, ADR, AgDR, migration AgDR, C4 diagrams).

The full role roster, workflow detail, and template catalogue live in docs/whats-inside.md. The canonical entry point Claude Code reads is CLAUDE.md.

Show you're governed by ApexYard

Running your repo under ApexYard? Add a badge to its README. Every adopter repo that carries one is a backlink and a bit of social proof — and /handover will offer to drop it into the repos it onboards.

Governed by — for a repo managed under an ApexYard ops fork:

[![Governed by ApexYard](https://img.shields.io/badge/governed_by-ApexYard-2F6DF6?style=flat-square)](https://github.com/me2resh/apexyard)

Built with — for a project built out through the ApexYard workflow:

[![Built with ApexYard](https://img.shields.io/badge/built_with-ApexYard-2F6DF6?style=flat-square)](https://github.com/me2resh/apexyard)

Customization

ApexYard is designed to be customized. Every role, workflow, and template can be modified to fit your team:

1. Add roles: Create new .md files in roles/your-department/
2. Modify workflows: Edit files in workflows/
3. Add templates: Drop new templates in templates/
4. Override anything: The stack is just markdown files -- edit freely

Contributing

Contributions are welcome — start with CONTRIBUTING.md for the full fork → PR → review flow, and open issues with the Bug report / Feature request templates. All participation is governed by our Code of Conduct. Security issues go through SECURITY.md (private reporting), not public issues.

ApexYard runs on its own rules, so the flow mirrors any project under ApexYard governance:

1. File an issue — open a GitHub issue with the Bug report / Feature request template. If you run apexyard yourself, the /report-apexyard-bug and /request-apexyard-feature skills file it here for you (they target me2resh/apexyard — distinct from /bug and /feature, which file into your own managed project).
2. Start the ticket — /start-ticket <number> so the ticket-first hook lets your code edits through.
3. Branch + commit — {type}/GH-{number}-{short-description}, conventional commit format (type(#number): subject).
4. Self-check before pushing — npm run lint / markdownlint / shellcheck as applicable; hooks remind you at git push.
5. Open a PR — title type(#number): description + a Glossary section in the body.
6. Wait for Rex — the Code Reviewer agent auto-runs on every PR.
7. Merge requires two markers — Rex's approval + explicit per-PR human approval via /approve-merge <pr>. Plan-level "go" doesn't count.

For larger changes (new skills, rule changes, workflow redesigns), open a discussion or draft PRD first.

Contributors

Thanks to everyone who has helped forge ApexYard:

me2resh

AbdElrahmaN31

HishamM1

tifa64

hossam-96

aniketshukla1

_{This list credits every human directly, since squash-merges hide them from GitHub's contributor graph. New contributor? Open a PR and you'll be added.}

License

MIT License. See LICENSE for details.

---

Built with real-world experience shipping software with Claude Code.