---
id: ADR-0.17.0-agentsmd-tidy-control-surface-schema-and-rules-mir
status: Validated
kind: feature
semver: 0.17.0
lane: heavy
parent:
date: 2026-03-15
---

# ADR-0.17.0: AGENTS.md Tidy: Control Surface Schema and Rules Mirroring

## Intent

1. **Reduce context window bloat** — ~80% token reduction in always-loaded content
2. **Maintain strict agent guardrails** — governance rules must reach Claude reliably
3. **AGENTS.md-first posture** — AGENTS.md stays authoritative for cross-agent operations (Claude, Copilot, Codex)
4. **gzkit owns the schema** — vendor formats are projections, not sources of truth

## Decision

### Three-layer control surface model

```
Layer 1: Canonical Artifacts (gzkit-owned, validated)
  .gzkit/skills/*/SKILL.md          — skill definitions
  .github/instructions/*.md         — rule/instruction definitions
  .gzkit/hooks/*.py                 — hook definitions (future)
  .gzkit/schemas/*.schema.json      — validation schemas

Layer 2: Vendor Mirrors (generated by gz agent sync, never edited)
  .claude/skills/    — skill mirror for Claude Code
  .claude/rules/     — rules mirror for Claude Code
  .claude/hooks/     — hook mirror for Claude Code
  .github/skills/    — skill mirror for Copilot
  .agents/skills/    — skill mirror for Codex

Layer 3: Control Surface Documents (generated from templates + Layer 1)
  AGENTS.md          — universal agent contract
  CLAUDE.md          — Claude Code entry point
  .github/copilot-instructions.md  — Copilot entry point
```

### Vendor projection map

```
Canonical (gzkit-owned)          ->  Vendor Mirror (generated)
-----------------------------    -----------------------------
.gzkit/skills/*/SKILL.md        ->  .claude/skills/*/SKILL.md
                                ->  .github/skills/*/SKILL.md
                                ->  .agents/skills/*/SKILL.md

.github/instructions/*.md       ->  .claude/rules/*.md
                                ->  (Copilot reads directly)
                                ->  .agents/rules/*.md (future)

.gzkit/hooks/*.py               ->  .claude/hooks/*.py
                                ->  (Copilot: .github/hooks/)
```

## Consequences

### Positive

Governance visibility for superpowers work.

### Negative

Additional booking step in workflow.

## Decomposition Scorecard

<!-- Deterministic OBPI sizing: score each dimension 0/1/2. -->
<!-- Cutoffs are notional defaults and should be calibrated over time from project evidence. -->

Auto-generated by gz superbook.

## Checklist

<!-- Each item becomes an OBPI (One Brief Per Item). Sequential numbering, no gaps. -->

- [ ] OBPI-0.17.0-01: Categorized Skill Catalog
- [ ] OBPI-0.17.0-02: Rules Mirroring
- [ ] OBPI-0.17.0-03: Slim CLAUDE.md Template
- [ ] OBPI-0.17.0-04: JSON Schemas and Validation
- [ ] OBPI-0.17.0-05: Manifest Update and Final Sync

## Q&A Transcript

<!-- Interview transcript preserved for context -->

Generated from superpowers spec.

## Evidence

<!-- Links to tests, documentation, and other artifacts that prove completion -->

- [ ] Tests: `tests/`
- [ ] Docs: `docs/`

## Alternatives Considered

Manual gz plan + gz specify (two-step).

## Attestation Block

| Term | Status | Attested By | Date | Reason |
|------|--------|-------------|------|--------|
| 0.17.0 | Completed | Jeff | 2026-03-20 | completed |
