AI Coding

Part 6 — The common harness: architecture and build plan

What does the harness repo look like, and what do I build first?

8 min · Updated June 2026

You’ve read the whole map. Now you need to build something. This section gives you the actual repo structure, the full cross-vendor mapping table, the asset checklist organized by phase, and a direct answer to the question every platform engineer eventually asks: if I only have time for ten things, what are they?

Download templates

All Part 6 templates (.zip)Download

The complete harness bundle — skeleton repo, mapping sheets, checklist, quick-start, and scorecard in one download. Mid-2026 snapshot — copy and edit, don't run as-is.

Q6.1 — What does the common harness repo actually look like?

One platform repo, vendor-neutral sources plus per-vendor compiled outputs:

acme/dev-platform/

acme/dev-platform/
├── AGENTS.md                       # Canonical cross-vendor context
├── CLAUDE.md                       # @AGENTS.md + Claude-specific overrides
├── .claude-plugin/marketplace.json # Claude marketplace manifest
├── .github/
│   ├── copilot-instructions.md
│   ├── agents/                     # Copilot custom agents (.agent.md)
│   ├── instructions/               # Path-scoped (applyTo)
│   ├── chatmodes/                  # Custom chat modes
│   ├── prompts/                    # Reusable prompt files
│   └── workflows/                  # GitHub Agentic Workflows (*.md)
├── agents/                         # Vendor-neutral agent source
├── skills/                         # SKILL.md folders (cross-platform)
├── hooks/                          # Hook scripts + manifests
├── mcp-servers/                    # MCP server manifests (the allowlist)
├── plugins/                        # Claude-side plugin packages
├── policies/
│   ├── claude/
│   │   ├── managed-settings.json
│   │   └── managed-settings.d/     # Team-owned policy fragments
│   └── github/ai-controls.md
├── templates/                      # Per-repo bootstrap templates
└── scripts/                        # bootstrap, compile, publish

The rule: author once in the vendor-neutral folders (skills/, agents/, mcp-servers/, hooks/), and let scripts/ compile and publish to both the .claude-plugin/ and .github/ targets.

Download templates

dev-platform/ — README (architecture map + quick start)Download

dev-platform/ — complete skeleton (.zip)Download

Complete platform repo skeleton with every folder from the Q6.1 tree. scripts/compile.sh compiles vendor-neutral sources into both Claude and Copilot targets and includes a --check drift-gate mode for CI. Fill the placeholders using the Parts 2–5 templates.

Q6.2 — Give me the full Claude Code–to–Copilot mapping so I know what compiles to what.

Concept	Claude Code	GitHub Copilot	Harness approach
Project memory	CLAUDE.md (hierarchical)	copilot-instructions.md + AGENTS.md	One canonical AGENTS.md; thin per-vendor wrappers
Path-scoped rules	Subdirectory CLAUDE.md	*.instructions.md with applyTo	Folder-scoped on Claude; applyTo on Copilot
Custom agents	.claude/agents/*.md	.github/agents/*.agent.md	Shared prompt body, two frontmatter wrappers
Skills	.claude/skills/<name>/SKILL.md	.github/skills/<name>/SKILL.md	One source, distributed unchanged (same standard)
Slash commands / prompts	.claude/commands/*.md	.github/prompts/*.prompt.md	Neutral body in skills; slash wrappers per surface
Chat modes	Output styles / subagent persona	*.chatmode.md	Copilot-specific UX layer, mapped from agents/
Lifecycle hooks	21 events, 4 handlers	Agent hooks + Actions + gh-aw	Claude hooks = inner loop; gh-aw = outer loop
External tools	MCP via claude mcp add	MCP + built-in GitHub MCP	One MCP manifest set for both
Plugin distribution	Plugin marketplace	Org marketplace from private repo	Two manifests, CI compiles both
Enterprise policy	managed-settings.json + MDM	Enterprise AI Controls + rulesets	Both run together; intent in policies/
Sandboxing	/sandbox (Seatbelt/bubblewrap)	Actions runners + AWF + MCP gateway	Claude sandbox locally; AWF for automation
Audit	OpenTelemetry + Compliance API	Enterprise audit log streaming	Both into one SIEM, correlated on identity
Code review	Reviewer subagent + PostToolUse hook	Copilot code review + Autofix	Same code-review skill feeds both

Download templates

claude-copilot-mapping.xlsxDownload

claude-copilot-mapping.csvDownload

The full 1:1 capability mapping as a working file. The Authored-once-as and Compiles-to columns are the contract between your source folders and the two targets — this is what the compile script implements.

Q6.3 — What's the full asset checklist — what do I actually have to build?

Phase 0 — Foundations

[ ]Cloud backend for Claude inference chosen, model IDs pinned
[ ]GitHub Enterprise + Copilot Enterprise, AI Controls on
[ ]acme/dev-platform repo created
[ ]SIEM endpoint ready for OTLP + GitHub audit-log streaming
[ ]MDM working for managed-settings distribution

Phase 1 — Context

[ ]Canonical AGENTS.md (≤200 lines)
[ ]CLAUDE.md that @AGENTS.md-imports it
[ ].github/copilot-instructions.md (dense first 4,000 chars)
[ ]Per-team *.instructions.md with applyTo globs
[ ]Org-level Copilot custom instructions

Phase 2 — Capabilities

[ ]Skills: code-review, secure-coding-checklist, db-migration, regulatory-logging, pii-handling, incident-runbook, plus per-domain
[ ]Custom agents: code-reviewer, security-scout, pm-spec, architect-review, implementer-tester, docs-writer
[ ]MCP allowlist: code-intel, Jira, Confluence, Datadog/Sentry, API gateway
[ ]AST/graph code-intel MCP server indexed across the polyrepo (nightly, in VPC)
[ ]Claude Code LSP plugins enabled per primary language

Phase 3 — Control

[ ]Claude hook bundle: PreToolUse Bash firewall + protected-paths gate; PostToolUse lint/typecheck; SessionStart context injection; HTTP audit hooks
[ ]Agentic Workflows compiled --strict: triage, security-guard, daily-status, docs-sync, agents-md-maintainer
[ ]Repository rulesets: required PR review, auto Copilot review, required status checks
[ ]Branch protection on main for all repos (template-enforced)

Phase 4 — Governance

[ ]managed-settings.json + managed-settings.d/ fragments
[ ]MDM deployment (Jamf/Kandji, Intune/GPO, Linux pkg)
[ ]GitHub AI Controls: session monitoring, MCP registry URL, audit streaming
[ ]OpenTelemetry collector + SIEM dashboards
[ ]Scheduled Compliance API pull into the warehouse
[ ]Spend caps + per-team cost dashboards
[ ]AI-agent incident-response runbook

Phase 5 — Distribution

[ ].claude-plugin/marketplace.json published; each plugin has plugin.json
[ ]GitHub org Copilot marketplace synced from the platform repo
[ ]Group-level per-plugin overrides
[ ]Repository templates bootstrapping .github/ + AGENTS.md + CLAUDE.md
[ ]bootstrap-repo.sh for existing repos
[ ]Pilot → team → org rollout

Phase 6 — Continuous improvement

[ ]Quarterly skill-usage review (prune unused, split over-large)
[ ]Monthly audit-log anomaly review; tighten denies on stable signals
[ ]Weekly Agentic Workflow token-cost review
[ ]Track outcomes by cycle time, time-to-productive-contribution, incident resolution — not lines of code

Download templates

phased-asset-checklist.mdDownload

Phases 0–6 build checklist with exit criteria per phase. Notion-importable. This governs what you build; the rollout scorecard (below) governs how you deploy it.

Q6.4 — If I only have time for ten things this quarter, what are they?

1.AGENTS.md at the platform repo root, imported by CLAUDE.md and copilot-instructions.md.
2.Claude managed-settings.json — MCP allowlist, model pinning, secret denies, strictKnownMarketplaces.
3.One AST/graph code-intel MCP server in your VPC, indexed across the top ~20 repos.
4.A code-review skill, consumed by both the code-reviewer subagent and Copilot code review.
5.A PreToolUse Bash-firewall hook, shipped into every repo via template.
6.A PostToolUse format/lint hook, likewise.
7.An HTTP audit hook → internal endpoint → SIEM.
8.A GitHub repository ruleset template: required PR review, auto Copilot review, required status checks.
9.A security-guard.md GitHub Agentic Workflow.
10.The OpenTelemetry pipeline for Claude Code, with dashboards on claude_code.tool_decision and claude_code.mcp_server_connection.

These ten give you a functional harness — context, control, and audit — before you go broad.

Download templates

ten-things-quickstart.pdfDownload

The ten highest-leverage items as a one-page printable sprint board, colour-coded by harness layer. Pin it up; work top to bottom.

Q6.5 — What's a sane rollout sequence, and how do I know when to advance?

Four phases, each with an explicit gate. The gate is a measured decision, not a calendar event.

Phase ABuild the platformweeks 1–6

Stand up the repo, the canonical AGENTS.md, the first five skills, one AST/graph MCP server, and the managed-settings policy.

Gate: three internal pilot users can run both tools end to end with the harness installed.

Phase BPilotweeks 6–10

5–10 developers, one team, in audit mode — permissive allow rules, an HTTP hook logging everything, OTel live.

Gate: under 5% of sessions blocked unexpectedly; no OTel data gaps; audit endpoint uptime ≥99.5%.

Phase CDepartment rolloutweeks 10–16

20–50 developers. Tighten denies from Phase B data; add gh-aw workflows; turn on auto Copilot review.

Gate: cycle time stable or improving; no high-severity AI incidents; pilot teams self-report >25% gain; cost trending toward budget.

Phase DOrg-wide via MDMweeks 16+

Push managed settings to the fleet; lock strictKnownMarketplaces.

Gate: mature audit dashboards; AI-driven incidents triaged like human-driven ones.

Download templates

rollout-scorecard.xlsxDownload

Phases A–D gate-criteria scorecard with measurable thresholds and a Status dropdown. Advance a phase only when its gates are green.

Download templates

README — how the files fit togetherDownload

All Part 6 templates (.zip)Download

Full bundle and index. Treat the harness as a living product and re-verify vendor specifics before relying on them — this field moves monthly.