docs: add agent-facing documentation system#61
Merged
Conversation
Rewrite AGENTS.md with full domain vocabulary, security rules, code conventions, weaver-spec references, and documentation map. Add docs/agent-context/ canonical shared layer: - architecture.md: intent, boundaries, tradeoffs - workflows.md: authoritative commands, PR conventions, doc governance - invariants.md: weaver-spec compliance, forbidden shortcuts, ordering traps - lessons-learned.md: failure-capture workflow, recurring mistakes - review-checklist.md: pre-submit self-check, cross-file consistency Add tool-specific instruction files: - .github/copilot-instructions.md: review-critical projections for Copilot - .claude/CLAUDE.md: Claude-specific operating instructions Update CHANGELOG.md with new documentation entries.
There was a problem hiding this comment.
Pull request overview
Introduces a layered, canonical documentation system for AI coding agents in this repository, centralizing shared rules in AGENTS.md and docs/agent-context/, with tool-specific “projection” files for Copilot and Claude.
Changes:
- Rewrites
AGENTS.mdinto the canonical shared instruction layer (vocabulary, security rules, conventions, documentation map). - Adds
docs/agent-context/canonical docs (architecture, workflows, invariants, lessons learned, review checklist). - Adds tool-specific instruction layers (
.github/copilot-instructions.md,.claude/CLAUDE.md) and updatesCHANGELOG.md.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/agent-context/workflows.md | Defines authoritative commands, PR conventions, definition of done, and doc governance. |
| docs/agent-context/review-checklist.md | Adds a structured pre-submit/review checklist and cross-file consistency table. |
| docs/agent-context/lessons-learned.md | Captures a process for recording reusable mistakes/patterns. |
| docs/agent-context/invariants.md | Documents security invariants, forbidden shortcuts, and ordering traps. |
| docs/agent-context/architecture.md | Summarizes architectural intent, boundaries, and non-negotiable tradeoffs. |
| AGENTS.md | Establishes canonical agent instructions and a documentation map to all sources. |
| .github/copilot-instructions.md | Copilot-facing “review-critical” projection of canonical rules for PR review. |
| .claude/CLAUDE.md | Claude-specific operating guidance aligned to canonical shared docs. |
| CHANGELOG.md | Records the addition of the agent-facing documentation system. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a comprehensive, layered documentation system for AI coding agents (Copilot, Claude, and others) operating in this repository.
What changed
Rewritten:
AGENTS.md— expanded from 41 lines to ~145 lines with full domain vocabulary, security rules, code conventions, weaver-spec references, and a documentation map pointing to all canonical sources.Created (canonical shared layer —
docs/agent-context/):architecture.md— architectural intent, major boundaries, key tradeoffs, things not to simplify.workflows.md— authoritative commands table, PR conventions, definition of done, documentation governance.invariants.md— weaver-spec compliance (I-01, I-02, I-06), forbidden shortcuts ("never do" list), security-critical ordering traps, safe vs. unsafe changes.lessons-learned.md— failure-capture workflow, recurring mistake patterns (docstring mismatch, whitespace bypass, dead code).review-checklist.md— pre-submit self-check (CI gate, correctness, security, backward compat, code hygiene, documentation), cross-file consistency table.Created (tool-specific layers):
.github/copilot-instructions.md— projects review-critical rules visible during GitHub PR review (review checklist, invariants, convention discipline)..claude/CLAUDE.md— Claude-specific operating instructions (explore before acting, implement safely, validate, handle contradictions, capture lessons).Updated:
CHANGELOG.md— added entries for the new documentation system.Why
The previous
AGENTS.mdwas a minimal 41-line file that lacked security rules, code conventions, weaver-spec references, and a documentation map. AI agents had no guidance on invariants, review checks, or architectural boundaries. This change establishes a structured, layered system where:AGENTS.md+docs/agent-context/)Testing
ruff format— 36 files unchangedruff check— 2 pre-existing UP038 warnings insummarize.py(not from this PR)mypy— 0 issuespytest— 216 passed, 96% coverageDocs & AI agent instructions
This PR is the documentation and AI agent instruction update. All 8 files are documentation files.