Bobby NoelteandClaude Opus 5.5
d68f040206
Vendor the engineering skills of https://github.com/mattpocock/skills into ai/skills/engineering, with their MIT license, and list them in AGENTS.md. The agent-specific metadata (agents/openai.yaml) is kept for other agents. Additional changes - Add scripts/update_mattpocock_skills.py to compare the copy with upstream by git blob hashes from a blobless clone and to update it on request. - Add tests/test_ai.py; it warns when the copy differs from upstream and caches the upstream hashes in the pytest cache for a day. - Document the engineering skills in docs/develop/ai.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2.0 KiB
Domain Docs
How the engineering skills should consume this repo's domain documentation when exploring the codebase.
Before exploring, read these
GLOSSARY.mdat the repo root, orGLOSSARY-MAP.mdat the repo root if it exists: it points at oneGLOSSARY.mdper context. Read each one relevant to the topic.docs/adr/: read ADRs that touch the area you're about to work in. In multi-context repos, also checksrc/<context>/docs/adr/for context-scoped decisions.
If any of these files don't exist, proceed silently. Don't flag their absence; don't suggest creating them upfront. The /domain-modeling skill (reached via /grill-with-docs and /improve-codebase-architecture) creates them lazily when terms or decisions actually get resolved.
File structure
Single-context repo (most repos):
/
├── GLOSSARY.md
├── docs/adr/
│ ├── 0001-event-sourced-orders.md
│ └── 0002-postgres-for-write-model.md
└── src/
Multi-context repo (presence of GLOSSARY-MAP.md at the root):
/
├── GLOSSARY-MAP.md
├── docs/adr/ ← system-wide decisions
└── src/
├── ordering/
│ ├── GLOSSARY.md
│ └── docs/adr/ ← context-specific decisions
└── billing/
├── GLOSSARY.md
└── docs/adr/
Use the glossary's vocabulary
When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in GLOSSARY.md. Don't drift to synonyms the glossary explicitly avoids.
If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for /domain-modeling).
Flag ADR conflicts
If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
Contradicts ADR-0007 (event-sourced orders), but worth reopening because…