docs: normalize apple-dev-skills repo guidance

Author: gaelic-ghost

.github/scripts/validate_repo_docs.sh

@@ -26,6 +26,7 @@ echo "Validating roadmap presence..."
 
 echo "Validating root docs presence..."
 [[ -f README.md ]] || fail "Missing README.md at repo root."
+[[ -f CONTRIBUTING.md ]] || fail "Missing CONTRIBUTING.md at repo root."
 [[ -f AGENTS.md ]] || fail "Missing AGENTS.md at repo root."
 [[ -f docs/maintainers/workflow-atlas.md ]] || fail "Missing docs/maintainers/workflow-atlas.md."
 [[ -f docs/maintainers/reality-audit.md ]] || fail "Missing docs/maintainers/reality-audit.md."
@@ -45,9 +46,18 @@ require_contains "README.md" 'This repository is the canonical source of truth f
 require_contains "README.md" 'Treat root [`skills/`](./skills/) as the canonical authored surface.'
 require_contains "README.md" 'Keep shared reusable assets in [`shared/`](./shared/)'
 require_contains "README.md" 'Run the repository test suite for skill and metadata changes:'
+require_contains "README.md" 'Use [`CONTRIBUTING.md`](./CONTRIBUTING.md) for maintainer workflow details'
 require_not_contains "README.md" 'plugins/apple-dev-skills/'
 require_not_contains "README.md" 'install-plugin-to-socket'
 
+echo "Validating CONTRIBUTING contract..."
+require_contains "CONTRIBUTING.md" 'Use this guide when preparing changes so the repository stays understandable, testable, and truthful about the Apple workflow surface it actually ships.'
+require_contains "CONTRIBUTING.md" '## Contribution Workflow'
+require_contains "CONTRIBUTING.md" '## Local Setup'
+require_contains "CONTRIBUTING.md" '## Development Expectations'
+require_contains "CONTRIBUTING.md" 'bash .github/scripts/validate_repo_docs.sh'
+require_contains "CONTRIBUTING.md" 'uv run pytest'
+
 echo "Validating AGENTS contract..."
 require_contains "AGENTS.md" 'This repository is the canonical home for Gale'"'"'s Apple, Swift, and Xcode workflow skills.'
 require_contains "AGENTS.md" 'Treat `productivity-skills` as the default baseline maintainer layer'
@@ -85,6 +95,7 @@ require_contains "$audit_doc" "## Audit Procedure"
 require_contains "$audit_doc" "## Local Discovery Smoke Test Flow"
 require_contains "$audit_doc" "## Reporting Shape"
 require_contains "$audit_doc" 'this repository'"'"'s shipped Apple plugin owns the end-user toolkit contract'
+require_contains "$audit_doc" 'Historical milestone planning decisions that no longer need standalone docs should live in `ROADMAP.md`'
 require_not_contains "$audit_doc" 'plugins/apple-dev-skills/'
 
 echo "Validating customization consolidation review..."

AGENTS.md

@@ -1,13 +1,31 @@
 # AGENTS.md
 
-## Repository Role
+Use this file for durable repo-local guidance that Codex should follow before changing code, docs, or project workflow surfaces in this repository.
+
+## Repository Scope
+
+### What This File Covers
 
 - This repository is the canonical home for Gale's Apple, Swift, and Xcode workflow skills.
 - Treat `productivity-skills` as the default baseline maintainer layer for general repo docs and maintenance work; this repo is the narrower specialist layer when Apple-specific behavior should change the workflow.
 - Root `skills/` is the canonical authored and exported surface.
 - Keep shared reusable assets in [`shared/`](./shared/) and maintainer tests in [`tests/`](./tests/).
 
-## Apple-specific Rules
+### Where To Look First
+
+- Start with [`README.md`](./README.md), [`CONTRIBUTING.md`](./CONTRIBUTING.md), [`ROADMAP.md`](./ROADMAP.md), [`docs/maintainers/workflow-atlas.md`](./docs/maintainers/workflow-atlas.md), and [`docs/maintainers/reality-audit.md`](./docs/maintainers/reality-audit.md).
+- When a task touches one shipped workflow, read the corresponding directory under [`skills/`](./skills/) before inferring policy from sibling skills or older maintainer notes.
+- Use [`.github/scripts/validate_repo_docs.sh`](./.github/scripts/validate_repo_docs.sh) and the pytest suite as the enforced source-of-truth checks for public-doc drift.
+
+## Working Rules
+
+### Change Scope
+
+- Keep work bounded to the smallest coherent docs, skill, validator, and test surface that resolves the real drift.
+- If a task starts needing a new active skill, a new export surface, or a broad repo-structure change, stop and surface that scope change before continuing.
+- Collapse retired historical planning notes into `ROADMAP.md` or still-live maintainer docs instead of preserving stale standalone docs.
+
+### Source of Truth
 
 - For Swift, Apple framework, Apple platform, SwiftUI, SwiftData, Observation, AppKit, UIKit, Foundation-on-Apple, or Xcode-related guidance, require reading the relevant Apple documentation before proposing implementation changes.
 - State the documented Apple behavior being relied on before design or code changes are proposed.
@@ -21,7 +39,64 @@
 - Keep `Package.swift` explicit about its package-wide Swift language mode. On current Swift 6-era manifests, prefer `swiftLanguageModes: [.v6]` as the default declaration and treat `swiftLanguageVersions` as a legacy alias used only when an older manifest surface requires it.
 - Treat `Package.resolved` and similar package-manager outputs as generated files. Do not tell agents to hand-edit them.
 
-## Export Boundaries
+### Communication and Escalation
+
+- Surface non-obvious tradeoffs before widening a change from one skill or one doc into repo-wide wording or policy.
+- When docs, validator rules, and tests disagree, explain which surface is stale and what you are changing to bring them back into alignment.
+- If a historical maintainer doc still contains live decisions, move those decisions into the active docs before deleting the old file.
+
+## Commands
+
+### Setup
+
+```bash
+uv sync --dev
+```
+
+### Validation
+
+```bash
+bash .github/scripts/validate_repo_docs.sh
+uv run pytest
+```
+
+### Optional Project Commands
+
+```bash
+uv run python .github/scripts/validate_skill_creator_contract.py
+```
+
+Use the extra validator when a change touches the skill-creator contract or repo-doc rules that mention it.
+
+## Review and Delivery
+
+### Review Expectations
+
+- Explain which shipped docs, validator rules, and tests changed and why.
+- Call out deleted or consolidated maintainer docs explicitly so reviewers can see where their durable conclusions moved.
+- Keep docs-only cleanup distinct from behavior-changing skill work when that split helps review.
+
+### Definition of Done
+
+- The changed root docs, maintainer docs, validator rules, and tests all describe the same live repository behavior.
+- Grounded validation has been run or any skipped checks are called out plainly.
+- Nearby docs and roadmap history have been updated when the change retires stale planning notes or changes the public workflow contract.
+
+## Safety Boundaries
+
+### Never Do
 
-- Keep root `skills/` as the canonical authored surface even though the repo ships plugin packaging metadata.
 - Do not reintroduce nested packaged plugin trees or alternate export surfaces under `plugins/`.
+- Do not weaken the Apple docs-first rule or present Apple behavior from memory when current docs are available.
+- Do not tell maintainers to hand-edit generated package-manager state such as `Package.resolved`.
+- Do not preserve stale historical planning docs as live guidance once their durable conclusions have already been absorbed elsewhere.
+
+### Ask Before
+
+- Ask before adding or removing active skills, changing the top-level export shape, or broadening the repository into a new product surface.
+- Ask before deleting a maintainer doc whose decisions have not yet been folded into `ROADMAP.md` or a still-live maintainer reference.
+- Ask before changing repo-wide policy that would affect downstream synced or bootstrapped guidance assets.
+
+## Local Overrides
+
+This repository does not currently use deeper `AGENTS.md` files under `skills/` or `docs/`. Treat this root file as the repo-wide agent contract, and use the individual skill docs plus maintainer references to refine behavior for the specific surface you are editing.

CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Contributing to apple-dev-skills
+
+Use this guide when preparing changes so the repository stays understandable, testable, and truthful about the Apple workflow surface it actually ships.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Contribution Workflow](#contribution-workflow)
+- [Local Setup](#local-setup)
+- [Development Expectations](#development-expectations)
+- [Pull Request Expectations](#pull-request-expectations)
+- [Communication](#communication)
+- [License and Contribution Terms](#license-and-contribution-terms)
+
+## Overview
+
+### Who This Guide Is For
+
+Use this guide when you are changing the shipped skills, the maintainer docs, the validator, or the supporting tests for this repository.
+
+### Before You Start
+
+Read [`README.md`](./README.md), [`ROADMAP.md`](./ROADMAP.md), [`AGENTS.md`](./AGENTS.md), [`docs/maintainers/workflow-atlas.md`](./docs/maintainers/workflow-atlas.md), and [`docs/maintainers/reality-audit.md`](./docs/maintainers/reality-audit.md) before broadening a docs or workflow change. If the work touches one specific skill, read that skill directory first instead of generalizing from sibling skills.
+
+## Contribution Workflow
+
+### Choosing Work
+
+Take work from the live repo surface, not from stale planning notes. Use `ROADMAP.md` for current milestone status, the validator and tests for the enforced public contract, and the active skill directories under [`skills/`](./skills/) for the shipped behavior.
+
+### Making Changes
+
+Keep changes bounded to the smallest coherent surface that fixes the real drift. When a shipped skill, maintainer doc, validator rule, or test expectation changes, update the nearby supporting docs and tests in the same pass so the repo stays self-consistent. Treat `README.md` as the public repo entrypoint, `CONTRIBUTING.md` as the maintainer workflow guide, `AGENTS.md` as durable agent policy, and `ROADMAP.md` as the durable planning and history surface.
+
+### Asking For Review
+
+Ask for review after the changed docs, validator expectations, and relevant tests agree with each other. Call out any deliberate scope cuts, any follow-up work left in `ROADMAP.md`, and any validation you could not run.
+
+## Local Setup
+
+### Runtime Config
+
+Sync the local maintainer environment with:
+
+```bash
+uv sync --dev
+```
+
+This repository does not require app secrets or background services for its normal docs and skill-validation workflow.
+
+### Runtime Behavior
+
+The repository is healthy when the docs validator passes, the pytest suite passes, and the root docs describe the same shipped surface as the active skill directories. Use [`docs/maintainers/reality-audit.md`](./docs/maintainers/reality-audit.md) when you need the repo's source-of-truth order or audit procedure.
+
+## Development Expectations
+
+### Naming Conventions
+
+Keep skill names literal and workflow-oriented. Preserve the existing Apple-specific terminology, the current active skill names, and the repo's distinction between canonical authored surfaces under [`skills/`](./skills/) and packaging metadata under the plugin manifests.
+
+### Accessibility Expectations
+
+This repository does not currently maintain a separate root `ACCESSIBILITY.md`. When you change Apple accessibility guidance here, keep it grounded in current Apple documentation, update the relevant skill docs and tests in the same pass, and avoid presenting generic visual-design advice as if it were accessibility guidance.
+
+### Verification
+
+Use the grounded repo checks:
+
+```bash
+bash .github/scripts/validate_repo_docs.sh
+uv run pytest
+```
+
+Run additional targeted checks only when the changed surface has a narrower validation path worth calling out.
+
+## Pull Request Expectations
+
+Summarize what changed, why the docs or workflow contract needed to move, and which validator or test results support the change. Keep docs-only cleanup clearly separated from behavior-changing skill work when the split matters for review.
+
+## Communication
+
+Raise questions before widening scope into new skills, new export surfaces, or broader repo-structure changes. If a historical maintainer doc is no longer carrying live decision-making value, prefer collapsing its durable conclusions into `ROADMAP.md` or the still-live maintainer docs instead of preserving another orphan planning note.
+
+## License and Contribution Terms
+
+This repository is licensed under Apache 2.0. See [LICENSE](./LICENSE) for the governing contribution and reuse terms.

README.md

@@ -5,27 +5,19 @@ Apple, Swift, and Xcode workflow skills for Codex and Claude Code.
 ## Table of Contents
 
 - [Overview](#overview)
-- [Setup](#setup)
+- [Quick Start](#quick-start)
 - [Usage](#usage)
 - [Development](#development)
-- [Verification](#verification)
+- [Repo Structure](#repo-structure)
+- [Active Skills](#active-skills)
 - [Release Notes](#release-notes)
 - [License](#license)
-- [Active Skills](#active-skills)
-- [Repository Layout](#repository-layout)
 
 ## Overview
 
-`apple-dev-skills` bundles reusable workflows for Apple-platform development work across Swift, SwiftUI, Xcode, SwiftPM, testing, formatting, and repo-guidance maintenance.
-
 ### Status
 
-This repository is active and currently ships Apple-platform development skills plus shared maintainer resources and tests.
-
-Recent work strengthened two of the more infrastructure-heavy surfaces:
-
-- `structure-swift-sources` now has a clearer structural-cleanup contract, stronger file-header guidance, and a user-facing header inventory template.
-- `explore-apple-swift-docs` now teaches direct Xcode MCP and Dash lookup paths first, with Dash localhost HTTP documented as the direct machine-readable fallback.
+This repository is active and available for maintainer use.
 
 ### What This Project Is
 
@@ -35,13 +27,9 @@ This repository is the canonical source of truth for Gale's Apple, Swift, and Xc
 
 It exists to keep Apple-platform workflow guidance in one dedicated repository with explicit requirements around Apple documentation, Xcode-safe workflows, and clear source-of-truth boundaries.
 
-## Setup
+## Quick Start
 
-Sync the maintainer environment before running repo-local validation:
-
-```bash
-uv sync --dev
-```
+This repository is primarily the authored source tree for the shipped Apple workflow skills rather than an end-user app with a separate getting-started path. If you want to understand what the repo currently ships, start with [Active Skills](#active-skills) and [`docs/maintainers/workflow-atlas.md`](./docs/maintainers/workflow-atlas.md). If you want to modify the repository, go to [Development](#development) and use [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the maintainer workflow.
 
 ## Usage
 
@@ -57,32 +45,48 @@ Use this repository's skills when the work is about:
 - Apple-project guidance sync
 - Apple-platform documentation routing
 
+Use [`CONTRIBUTING.md`](./CONTRIBUTING.md) for maintainer workflow details, and use [`ROADMAP.md`](./ROADMAP.md) for planned and completed milestone-level work.
+
 ## Development
 
 ### Setup
 
-Treat root [`skills/`](./skills/) as the canonical authored surface. Keep shared reusable assets in [`shared/`](./shared/), maintainer docs in [`docs/`](./docs/), and install metadata in [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json) and [`.claude-plugin/marketplace.json`](./.claude-plugin/marketplace.json).
+Sync the maintainer environment before editing skills, tests, or maintainer docs:
+
+```bash
+uv sync --dev
+```
 
 ### Workflow
 
-Keep the repo honest about its Apple docs-first policy. When a skill changes, update the relevant tests and maintainer guidance in the same pass rather than letting the packaging or guidance drift.
+Treat root [`skills/`](./skills/) as the canonical authored surface. Keep shared reusable assets in [`shared/`](./shared/), maintainer docs in [`docs/`](./docs/), and install metadata in [`.codex-plugin/plugin.json`](./.codex-plugin/plugin.json) and [`.claude-plugin/marketplace.json`](./.claude-plugin/marketplace.json).
+
+Keep the repo honest about its Apple docs-first policy. When a skill changes, update the relevant tests and maintainer guidance in the same pass rather than letting the packaging or guidance drift. Use [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the normal contributor workflow and review expectations.
 
-## Verification
+### Validation
 
 Run the repository test suite for skill and metadata changes:
 
 ```bash
-uv sync --dev
+bash .github/scripts/validate_repo_docs.sh
 uv run pytest
 ```
 
-## Release Notes
-
-Use Git history and GitHub releases to track shipped changes for this repository.
-
-## License
+## Repo Structure
 
-See [LICENSE](./LICENSE).
+```text
+.
+├── .codex-plugin/
+├── .claude-plugin/
+├── AGENTS.md
+├── CONTRIBUTING.md
+├── README.md
+├── ROADMAP.md
+├── docs/maintainers/
+├── shared/
+├── skills/
+└── tests/
+```
 
 ## Active Skills
 
@@ -103,22 +107,10 @@ See [LICENSE](./LICENSE).
 - `xcode-build-run-workflow`
 - `xcode-testing-workflow`
 
-## Repository Layout
+## Release Notes
 
-```text
-.
-├── .claude-plugin/
-│   └── marketplace.json
-├── .codex-plugin/
-│   └── plugin.json
-├── AGENTS.md
-├── LICENSE
-├── README.md
-├── ROADMAP.md
-├── docs/
-├── pyproject.toml
-├── shared/
-├── skills/
-├── tests/
-└── uv.lock
-```
+Use Git history and GitHub releases to track shipped changes for this repository.
+
+## License
+
+See [LICENSE](./LICENSE).