Use this guide when preparing changes so the repository stays understandable, testable, and truthful about the Apple workflow surface it actually ships.
- Overview
- Contribution Workflow
- Local Setup
- Development Expectations
- Pull Request Expectations
- Communication
- License and Contribution Terms
Use this guide when you are changing the shipped skills, the maintainer docs, the validator, or the supporting tests for this repository.
Read README.md, ROADMAP.md, AGENTS.md, and 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.
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/ for the shipped behavior.
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.
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.
Sync the local maintainer environment with:
uv sync --devThis repository does not require app secrets or background services for its normal docs and skill-validation workflow.
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 when you need the repo's source-of-truth order or audit procedure.
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/ and packaging metadata under the plugin manifests.
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.
Use the grounded repo checks:
bash .github/scripts/validate_repo_docs.sh
uv run pytestRun additional targeted checks only when the changed surface has a narrower validation path worth calling out.
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.
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.
This repository is licensed under Apache 2.0. See LICENSE for the governing contribution and reuse terms.