Skip to content

docs: add contribution baseline and AI use policy, trim agent guides - #703

Merged
dev-jodee merged 2 commits into
mainfrom
docs/contributing-and-agent-guides
Aug 27, 2026
Merged

docs: add contribution baseline and AI use policy, trim agent guides#703
dev-jodee merged 2 commits into
mainfrom
docs/contributing-and-agent-guides

Conversation

@dev-jodee

Copy link
Copy Markdown
Collaborator

Summary

  • CONTRIBUTING.md: adopt the shared Foundation contribution structure (before-you-start checklist with signed commits, private vulnerability reporting, development setup, change requirements, PR expectations with Greptile resolution and Conventional Commits, license) on top of the existing repo-specific rules, which are unchanged.
  • CONTRIBUTING.md: new AI use section covering review responsibility, Solana Dev Skill / Solana MCP pointers, the AI code smells maintainers will close PRs over, disclosure, and reviewer communication. Two rules are specific to a teaching repo: generated code that obscures the pattern being taught is worse than none, and do not fan a change across every framework flavor unless it truly applies.
  • AGENTS.md: cut command tables, toolchain-pin lists, and formatting/CI steps that are all readable from package.json, Anchor.toml, and the workflows. Kept only the non-obvious parts: why this is not a pnpm workspace, workspace-ignore enforcement, the litesvm 0.8 override silent-pass trap, node:test-under-mocha exiting 0, resolver-2 feature unification, and the anchor keys sync drift guard. 4.4 KB to 2.3 KB.
  • games/gacha/pinocchio/CLAUDE.md and games/world-cup/pinocchio/CLAUDE.md: same treatment. Dropped just command tables, program file trees, account field dumps, and lifecycle walkthroughs; kept the design rationale (gacha's randomness and trust model, world-cup's total ranking key and folded scoring) and the traps (packed-field alignment, Codama literal-array limit, single-threaded light prover, devnet burst cost).

Test Plan

  • Docs only, no code paths touched.
  • pnpm check (prettier) was not run locally: the root node_modules is not installed in this working copy. CI covers it.

The root agent guide and the two per-example guides restated command tables,
directory trees, account layouts, and toolchain pins that are all readable
from the files themselves. Cut those and keep only the decisions and traps
that the code does not show: workspace layout intent, litesvm override
behavior, resolver-2 feature unification, keys-sync drift guard, and the
gacha randomness trust model.
Adopt the shared Foundation contribution structure: before-you-start
checklist with signed commits, private vulnerability reporting, development
setup, change requirements, and PR expectations including Greptile
resolution and Conventional Commits.

Add an AI use section covering review responsibility, the AI code smells
maintainers will close PRs over, disclosure, and reviewer communication,
plus two rules specific to a teaching repo: do not obscure the pattern
being taught, and do not fan a change across every framework flavor.

Existing repo-specific rules (pnpm, non-workspace layout, path structure,
LiteSVM, mandatory scripts, .ghaignore) are unchanged.
@dev-jodee
dev-jodee requested a review from amilz August 27, 2026 12:41
@greptile-apps

greptile-apps Bot commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

This documentation-only PR establishes a broader contribution and AI-use policy while reducing agent guides to repository-specific design decisions and traps.

  • Adds contribution setup, security reporting, pull-request, licensing, and AI-assistance expectations.
  • Condenses the root agent guide around workspace structure, test-stack hazards, and CI exceptions.
  • Condenses the Gacha and World Cup guides around their core mechanics, invariants, and specialized workflows.

Confidence Score: 4/5

The PR appears safe to merge after clarifying the non-blocking test-command guidance for justfile-driven Pinocchio examples.

The documentation changes preserve the checked game and repository invariants, with one misleading framework-wide command that sends contributors in two Pinocchio projects to a nonexistent package script.

Files Needing Attention: CONTRIBUTING.md

Important Files Changed

Filename Overview
CONTRIBUTING.md Adds the shared contribution baseline and AI policy, but its blanket Pinocchio test command misses the justfile-driven Gacha and World Cup exceptions.
AGENTS.md Removes discoverable command details while retaining workspace, test-harness, dependency, and CI traps.
games/gacha/pinocchio/CLAUDE.md Condenses the guide to the verified VRF trust model, accounting invariants, generation constraints, and specialized testing hazards.
games/world-cup/pinocchio/CLAUDE.md Condenses the guide to the verified ranking, score-folding, oracle immutability, event, generation, and workspace decisions.

Reviews (1): Last reviewed commit: "docs(contributing): add contribution bas..." | Re-trigger Greptile

Comment thread CONTRIBUTING.md
@dev-jodee
dev-jodee merged commit 4823810 into main Aug 27, 2026
20 checks passed
@dev-jodee
dev-jodee deleted the docs/contributing-and-agent-guides branch August 27, 2026 13:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants