# dev-platform — the common AI-coding harness

The single source of truth for your organization's AI-coding harness. You **author
vendor-neutral assets once** in the top-level source folders, and `scripts/compile.sh`
emits the two vendor-specific layouts (Claude and Copilot). Distribute the compiled
outputs via a private marketplace and a repo template.

> QRefAI *AI Coding Field Guide*, Part 6 (Q6.1). This is the capstone skeleton — the
> structure the whole series builds toward. Every file here is empty-but-valid; fill
> the `<PLACEHOLDER>`s using the templates from Parts 2–5.

## The one idea: author once, compile to both

```
            VENDOR-NEUTRAL SOURCE                 scripts/compile.sh            TARGETS
  ┌───────────────────────────────────────┐                            ┌──────────────────────┐
  │ skills/        (open SKILL.md standard)│ ──── identical ──────────▶ │ .claude/skills/      │
  │ agents/        (prompt body + meta)    │ ──── frontmatter xform ──▶ │ .github/skills/      │
  │ instructions/  (AGENTS.md canonical)   │ ──── adapters ───────────▶ │ CLAUDE.md            │
  │ mcp-servers/   (neutral registry)      │ ──── two config shapes ──▶ │ copilot-instructions │
  │ policies/      (managed + ruleset)     │ ──── split by vendor ────▶ │ .github/agents/*.md  │
  │ workflows/     (gh-aw sources)         │ ──── stage to Copilot ───▶ │ managed-settings.json│
  └───────────────────────────────────────┘                            │ rulesets / workflows │
                                                                        └──────────────────────┘
```

## Repository layout

```
dev-platform/
├── scripts/
│   └── compile.sh                 # ★ author-once → compile to both targets (+ --check for CI)
├── instructions/
│   ├── AGENTS.md                  # canonical, cross-vendor context (the source of truth)
│   ├── claude-overrides.md        # appended into the compiled CLAUDE.md
│   └── copilot-instructions.head.md  # front-loaded (<4,000-char) Copilot review rules
├── skills/                        # shared SKILL.md library (identical on both vendors)
│   ├── code-review/  secure-coding-checklist/  pii-handling/
│   ├── regulatory-logging/  db-migration/  incident-runbook/
│   └── <each has references/ for tier-3 material>
├── agents/                        # neutral prompt bodies → .md (Claude) + .agent.md (Copilot)
│   ├── security-reviewer.md
│   └── code-reviewer.md
├── mcp-servers/
│   └── manifest.json              # neutral server registry → two config shapes
├── policies/
│   ├── managed-settings.json      # Claude enterprise policy plane
│   └── main-protection.json       # GitHub branch-protection ruleset
├── workflows/
│   └── security-guard.md          # gh-aw source (compile with: gh aw compile --strict)
├── plugins/                       # additional bundled plugins (see plugins/README.md)
├── .claude-plugin/
│   ├── plugin.json                # primary bundle manifest
│   └── marketplace.json           # private marketplace catalog (SHA-pin plugins)
├── templates/
│   └── repo-template/             # what a NEW product repo inherits ("Use this template")
│       ├── AGENTS.md  CLAUDE.md
│       └── .github/ (copilot-instructions, CODEOWNERS, instructions, agents,
│                     workflows, rulesets)  +  .claude/settings.json
├── .github/workflows/compile-check.yml   # CI: fail on drift between source and build/
└── docs/ARCHITECTURE.md
```

## Quick start

```bash
# 1. Fill in the source files (placeholders) using the Part 2–5 templates.
# 2. Compile both targets:
scripts/compile.sh                 # → build/claude-plugin/ and build/github/
# 3. In CI, gate drift:
scripts/compile.sh --check         # non-zero exit if committed outputs are stale
# 4. Distribute: publish the marketplace; make templates/repo-template a GitHub template.
# 5. Onboard repos: "Use this template" for new repos; bootstrap-repo.sh (Part 4) for existing.
```

## How this connects to the rest of the series

- **Source files** come from the Part 2 (Claude), Part 3 (Copilot), and Part 5
  (AGENTS.md, skills) templates.
- **Distribution** (marketplace, template repo, `bootstrap-repo.sh`) is Part 4.
- **Governance** (managed-settings, ruleset, audit) threads through Parts 2–4.
- **The mapping sheet** (alongside this bundle) is the precise Claude↔Copilot
  correspondence the compiler implements.

`compile.sh` is a **stub**: the folder contracts, ordering, and the `--check` drift
gate are real; the per-file frontmatter transforms are marked `TODO` for you to wire
to your asset shapes.

_Snapshot of the mid-2026 consensus. Re-verify vendor specifics before relying on
them — this field moves monthly._