Skip to content

Add AI rules through agent docs - #563

Open
JieXiong9119 wants to merge 4 commits into
develop-v2from
feat/add-ai-agent-doc
Open

JieXiong9119 wants to merge 4 commits into
develop-v2from
feat/add-ai-agent-doc

Conversation

@JieXiong9119

Copy link
Copy Markdown
Contributor

Any background context you want to provide?

Contributors increasingly use AI coding agents (GitHub Copilot, Claude Code, Codex, Cursor) on this repo. The rules for changing the schema are currently spread across docs/versioning.md, docs/developer_resources.md, docs/release_instructions.md, proposals/README.md, .github/CONTRIBUTING.md, the PR template, .github/workflows/CI_Labels.yml, spec/validation_spec.rb, and the deprecation policy in the XSD header. Agents don't reliably find all of these, so they make avoidable mistakes such as breaking changes in minor releases, editing CHANGELOG.md or the version in feature PRs, adding duplicate element names, or using xs:complexContent.

What does this PR do?

Adds one canonical rules file for AI agents, plus pointer files for each tool. Closes #562.

  • AGENTS.md (canonical): repo layout, commands, the six rules enforced by spec/validation_spec.rb, breaking/non-breaking/patch classification and the deprecation policy, the schema-change workflow (proposal, XSD, examples, linking docs, tests), PR rules (one change per PR, required labels, release cutoffs), and expected agent behavior.
  • .claude/CLAUDE.md: imports AGENTS.md for Claude Code.
  • .github/copilot-instructions.md: points Copilot to AGENTS.md.
  • .github/instructions/schema-xsd.instructions.md (applies to BuildingSync.xsd): structure, documentation and units, enumerations, ID/IDref, auc:Source/auc:Status, UserDefinedFields, and how to word deprecations.
  • .github/instructions/proposals.instructions.md (applies to proposals/**/*.md): where proposals go, how to name them, required sections, and what breaking proposals must discuss.

All content comes from existing docs, workflows and tests, or from patterns already used in the XSD. No new policy is introduced. No changes to the schema, examples, tests or CI.

How should this be manually tested?

  1. poetry run pre-commit run --all-files passes.
  2. Open the repo with Copilot, Claude Code or another agent and ask it to make a small schema change (e.g. Element and simpletype have same name #428, renaming the Tightness simpleType). Check that it:
    • classifies the change as breaking, non-breaking or patch;
    • doesn't edit CHANGELOG.md or the version;
    • runs bundle exec rake remove_tabs, bundle exec rake and bundle exec rake generate_data_dictionary.
  3. Check that the links in AGENTS.md resolve.

What are the relevant tickets?

Screenshots (if appropriate)

@JieXiong9119 JieXiong9119 self-assigned this Oct 21, 2026
@JieXiong9119 JieXiong9119 added enhancement Non-breaking Change feature Adding new functionality to BuildingSync Schema: No Changes No updates to the BuildingSync Schema labels Oct 21, 2026
@JieXiong9119
JieXiong9119 requested a review from kflemin October 21, 2026 21:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement feature Adding new functionality to BuildingSync Non-breaking Change Schema: No Changes No updates to the BuildingSync Schema

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add AI assistant rules (Copilot / agent instructions) for the schema repo

1 participant