docs: add guidance for contributors using AI coding agents

[adityatiwari101104]

What does this PR do?

Adds a short "Working with AI Coding Agents" section to CONTRIBUTING.md, under Pull Requests.

The rules that matter most for AI-assisted PRs already exist in this guide but are spread across several sections: branch off upstream/v8, one concern per PR, regression tests that fail before the fix, never hand-edit generated skill files, run pytest/ruff/pyright, and disclose AI help with Co-Authored-By:. This section collects them in one place so a contributor, or the agent they point at this file, finds them together. It adds no new policy; every bullet restates an existing rule.

It also mentions ContribOS in one optional line, as a tool that lists these rules with file and line references and checks a branch against them. I build ContribOS. I asked whether to open this PR in the replies to this post on X, and @safishamsi replied "go for it": https://x.com/safishamsii/status/2107426119683067927. If you would rather keep the guide tool-neutral, I am happy to drop that line.

Type of change

• Bug fix
• New feature
• Documentation
• Tests or CI
• Refactor
• Security fix

Verification & Invariants

Documentation only. No code, generated skill fragments or persisted state are touched, so no extraction, cache or provenance invariant is affected. The section only restates rules already in CONTRIBUTING.md, so it should not drift from them; if those rules change, this section needs the same update.

• Read the CONTRIBUTING.md guide.
• Reproduced the issue and identified the invariant. (Not applicable: docs change.)
• Made the smallest fix necessary.
• Added a regression test (if bug fix) or isolated boundary test. (Not applicable: docs change.)
• Kept the PR description synchronized with the final implementation.
• Documented any limitations / unsupported cases explicitly.

How was this tested?

git diff --check                      # no whitespace problems
python -m tools.skillgen --check      # Check OK: 134 artifact(s) match committed output and expected/.
contribos policy (run on this branch) # reads the new section as CONTRIBUTING.md:133; AI-policy verdict unchanged

I did not run the pytest/ruff/pyright suites, since no Python file changed.

Graphify-specific checklist

• I updated generated skill artifacts (uv run python -m tools.skillgen --bless) when changing their source fragments. (Not applicable: no fragments changed; --check passes.)
• I confirmed that AST/structural extraction remains deterministic (no ambient state dependencies like ENV variables).
• I reviewed changes for security implications (no unsafe interpolation into shell/Python).
• I confirmed that no API keys or local-only graph data are included.
• (If applicable) I disclosed AI authorship in my commit messages.

[github-actions]

Thanks for the pull request, @adityatiwari101104. A maintainer will review it soon.

Want to talk it through while it is in review? Come join us on our Discord server. For longer-form discussion there is also GitHub Discussions.

A couple of things that speed up review: make sure the test suite passes on Python 3.10 and 3.13, and that the change keeps extraction deterministic.

[graphify-labs]

Graphify reviewed this change.

Looks safe to merge — no coupling regressions and no blocking issues, checked against the code graph (not a self-assessment).

---

Graphify review — findings

Adds a "Working with AI Coding Agents" section to CONTRIBUTING.md, making clear that every contribution rule applies to agent-written code and that the human stays the PR author. Contributors point the agent at CONTRIBUTING.md and ARCHITECTURE.md, branch off upstream/v8, and never let it hand-edit generated skill files. They also confirm regression tests fail without the fix, run pytest/ruff/pyright themselves, disclose AI help via Co-Authored-By:, and write the PR description by hand, with optional ContribOS tooling suggested for pre-PR policy checks.

No blocking issues surfaced.

Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 23 functions depend on the 23 functions this change touches.

Health — grade A; no new coupling hotspots.

Verification — 23 functions in the blast radius were not formally verified this run (proofs are advisory here).

Gate & verification

graphify gate

PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

• verification_scope: 23 function(s) in the blast radius were not formally verified this run

Test selection

Test selection

337 of 337 test file(s) selected (100%) via static blast radius.

Escalated to a full run for safety — the selection is not trustworthy on its own (see below). CI should run the whole suite.

• tests/test_affected_cli.py — full-run-safety
• tests/test_affected_member_seed.py — full-run-safety
• tests/test_agents_platform.py — full-run-safety
• tests/test_analyze.py — full-run-safety
• tests/test_anthropic_custom_endpoint.py — full-run-safety
• tests/test_antigravity_install.py — full-run-safety
• tests/test_apm_fallback_version.py — full-run-safety
• tests/test_architecture_doc.py — full-run-safety
• tests/test_astro_extraction.py — full-run-safety
• tests/test_astro_import_ids.py — full-run-safety
• tests/test_atomic_canvas_export.py — full-run-safety
• tests/test_atomic_version_stamp.py — full-run-safety
• tests/test_atomic_writes.py — full-run-safety
• tests/test_backend_env_isolation.py — full-run-safety
• tests/test_backend_extras.py — full-run-safety
• tests/test_benchmark.py — full-run-safety
• tests/test_benchmark_raw_graph.py — full-run-safety
• tests/test_blade_extractor.py — full-run-safety
• tests/test_build.py — full-run-safety
• tests/test_build_located_semantic_identity.py — full-run-safety
• tests/test_build_merge_dedup_scope.py — full-run-safety
• tests/test_build_merge_hyperedges_and_prune.py — full-run-safety
• tests/test_build_merge_shrink_guard.py — full-run-safety
• tests/test_builtin_global_type_refs.py — full-run-safety
• tests/test_cache.py — full-run-safety
• tests/test_callflow_html.py — full-run-safety
• tests/test_cargo_introspect.py — full-run-safety
• tests/test_cargo_missing_manifest.py — full-run-safety
• tests/test_carried_hyperedge_remap.py — full-run-safety
• tests/test_case_sensitive_resolution.py — full-run-safety
• tests/test_charmap_encoding.py — full-run-safety
• tests/test_chunking.py — full-run-safety
• tests/test_cjs_module_extension.py — full-run-safety
• tests/test_claude_cli_backend.py — full-run-safety
• tests/test_claude_md.py — full-run-safety
• tests/test_cli_broken_pipe.py — full-run-safety
• tests/test_cli_export.py — full-run-safety
• tests/test_cli_help.py — full-run-safety
• tests/test_cluster.py — full-run-safety
• tests/test_cluster_exclude_hubs.py — full-run-safety
• tests/test_cobol_extractor.py — full-run-safety
• tests/test_codebuddy.py — full-run-safety
• tests/test_community_hub_labels.py — full-run-safety
• tests/test_community_labels_skill.py — full-run-safety
• tests/test_confidence.py — full-run-safety
• tests/test_corrupt_graph_json.py — full-run-safety
• tests/test_cpp_method_declarations.py — full-run-safety
• tests/test_cpp_nested_and_cli.py — full-run-safety
• tests/test_cpp_objc_cross_file_calls.py — full-run-safety
• tests/test_cpp_preprocess.py — full-run-safety
• … and 287 more

non-code file(s) changed (CONTRIBUTING.md) → running the full suite for safety (a code graph can't see config/fixture/data deps)

changed code file(s) with no mapped test (CONTRIBUTING.md) — a coverage gap or a missing link — running the full suite rather than only the selected tests

Selection is safe under the controlled-regression assumption; always-run tests + a periodic full run are the backstops. Advisory — it never changes the check verdict.

[safishamsi]

Landed in v0.9.81. The AI-contributor guidance is accurate and a good addition. I dropped only the final ContribOS line before merging — we keep CONTRIBUTING.md tool-neutral and don't endorse a specific external tool in the canonical guide (you'd flagged you were happy to drop it). Everything else shipped as written. Thanks @adityatiwari101104!